Kebijakan XMLtoJSON

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Apa

Kebijakan ini mengonversi pesan dari format extensible markup language (XML) ke JavaScript Object Notation (JSON), sehingga memberi Anda beberapa opsi untuk mengontrol cara pesan dikonversi.

Dengan asumsi bahwa tujuannya adalah mengonversi respons berformat XML menjadi respons berformat JSON, kebijakan akan dilampirkan ke Alur respons (misalnya, Response / ProxyEndpoint/PostFlow).

Tentang

Dalam skenario mediasi umum, kebijakan JSON ke XML pada alur permintaan masuk sering kali dipasangkan dengan kebijakan XML ke JSON pada alur respons keluar. Dengan menggabungkan kebijakan seperti ini, JSON API dapat diekspos untuk layanan backend yang secara native hanya mendukung XML.

Untuk skenario saat API digunakan oleh beragam aplikasi klien yang mungkin memerlukan JSON atau XML, format respons dapat ditetapkan secara dinamis dengan mengonfigurasi kebijakan JSON ke XML dan XML ke JSON agar dijalankan secara bersyarat. Lihat Variabel dan kondisi alur untuk penerapan skenario ini.

Contoh

Untuk pembahasan mendetail tentang konversi antara JSON dan XML, lihat Mengonversi antara XML dan JSON dengan Apigee: Hal-hal yang perlu Anda ketahui.

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi pada kebijakan ini.

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</DisplayName>
    <Source>response</Source>
    <OutputVariable>response</OutputVariable>
    <Options>
        <RecognizeNumber>true</RecognizeNumber>
        <RecognizeBoolean>true</RecognizeBoolean>
        <RecognizeNull>true</RecognizeNull>
        <NullValue>NULL</NullValue>
        <NamespaceBlockName>#namespaces</NamespaceBlockName>
        <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
        <NamespaceSeparator>***</NamespaceSeparator>
        <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
        <TextNodeName>TEXT</TextNodeName>
        <AttributeBlockName>FOO_BLOCK</AttributeBlockName>
        <AttributePrefix>BAR_</AttributePrefix>
        <OutputPrefix>PREFIX_</OutputPrefix>
        <OutputSuffix>_SUFFIX</OutputSuffix>
        <StripLevels>2</StripLevels>
        <TreatAsArray>
            <Path unwrap="true">teachers/teacher/studentnames/name</Path>
        </TreatAsArray>
    </Options>
    <!-- Use Options or Format, not both -->
    <Format>yahoo</Format>
</XMLToJSON>

Atribut <XMLtoJSON>

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">

Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:

&lt;DisplayName&gt; elemen

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI dengan nama natural language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Elemen <Source>

Variabel, permintaan, atau respons yang berisi pesan XML yang ingin Anda konversi ke JSON.

Header HTTP Content-type pesan sumber harus ditetapkan ke application/xml, jika tidak, kebijakan tidak akan diterapkan.

Jika <Source> tidak ditentukan, maka akan diperlakukan sebagai pesan (yang diselesaikan ke permintaan saat kebijakan dilampirkan ke alur permintaan, atau respons saat kebijakan dilampirkan ke alur respons).

Jika variabel sumber tidak dapat diselesaikan, atau diselesaikan ke jenis non-pesan, kebijakan akan menampilkan error.

<Source>response</Source>

Elemen <OutputVariable>

Menyimpan output konversi format XML ke JSON. Biasanya nilai ini sama dengan sumber, yaitu biasanya respons XML dikonversi menjadi respons JSON.

Payload pesan XML diuraikan dan dikonversi menjadi JSON, dan header Content-type HTTP pesan berformat XML ditetapkan ke application/json.

Jika OutputVariable tidak ditentukan, source akan diperlakukan sebagai OutputVariable. Misalnya, jika source adalah response, maka OutputVariable secara default adalah response.

<OutputVariable>response</OutputVariable>

<Options>

Opsi memberi Anda kontrol atas konversi dari XML ke JSON. Gunakan grup <Options>, yang memungkinkan Anda menambahkan setelan konversi tertentu, atau elemen <Format>, yang memungkinkan Anda mereferensikan template opsi yang telah ditentukan sebelumnya. Anda tidak dapat menggunakan <Options> dan <Format> secara bersamaan.

<Options> wajib diisi jika <Format> tidak digunakan.

Elemen <Options>/<RecognizeNumber>

Jika benar (true), kolom angka dalam payload XML akan mempertahankan format aslinya.

<RecognizeNumber>true</RecognizeNumber>

Perhatikan contoh XML berikut:

<a>
  <b>100</b>
  <c>value</c>
</a>

Jika true, dikonversi menjadi:

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

Jika false, dikonversi menjadi:

{
    "a": {
        "b": "100",
        "c": "value"
    }
}

Elemen <Options>/<RecognizeBoolean>

Memungkinkan konversi mempertahankan nilai benar/salah boolean, bukan mengubah nilai menjadi string.

<RecognizeBoolean>true</RecognizeBoolean>

Untuk contoh XML berikut:

<a>
  <b>true</b>
  <c>value</c>
</a>

Jika true, dikonversi menjadi:

{
    "a": {
        "b": true,
        "c": "value"
    }
}

Jika false, dikonversi menjadi:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

Elemen <Options>/<RecognizeNull>

Memungkinkan Anda mengonversi nilai kosong menjadi nilai null.

<RecognizeNull>true</RecognizeNull>

Untuk XML berikut:

<a>
  <b></b>
  <c>value</c>
</a>

Jika true, dikonversi menjadi:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

Jika false, dikonversi menjadi:

{
  "a": {
    "b": {},
    "c": "value"
  }
}

Elemen <Options>/<NullValue>

Menunjukkan nilai yang akan digunakan untuk mengonversi nilai null yang dikenali dalam pesan sumber. Secara default, nilainya adalah null. Opsi ini hanya efektif jika RecognizeNull benar (true).

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
Elemen <Options>/<NamespaceSeparator>

Gunakan elemen ini bersama-sama.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
<NamespaceSeparator>***</NamespaceSeparator>

Perhatikan contoh XML berikut:

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">
  <ns1:b>value</ns1:b>
</a>

Jika NamespaceSeparator tidak ditentukan, struktur JSON berikut akan dibuat:

{
    "a": {
        "b": "value"
    }
}

Jika elemen NamespaceBlockName, DefaultNamespaceNodeName, dan NamespaceSeparator masing-masing ditentukan sebagai #namespaces, &, dan ***, maka struktur JSON berikut akan dihasilkan:

{
    "a": {
        "#namespaces": {
            "&": "http://ns.com",
            "ns1": "http://ns1.com"
        },
        "ns1***b": "value"
    }
}

Elemen <Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>

Gunakan elemen ini bersama-sama.

Jika disetel ke true, konten elemen XML dikonversi menjadi properti string.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

Untuk XML berikut:

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

Jika TextAlwaysAsProperty disetel ke true dan TextNodeName ditentukan sebagai TEXT, struktur JSON berikut akan dihasilkan:

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

Jika TextAlwaysAsProperty disetel ke false dan TextNodeName ditentukan sebagai TEXT, struktur JSON berikut akan dibuat:

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}

Elemen <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

Gunakan elemen ini bersama-sama.

Memungkinkan Anda mengelompokkan nilai ke dalam blok JSON dan menambahkan awalan ke nama atribut.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName>
<AttributePrefix>BAR_</AttributePrefix>

Perhatikan contoh XML berikut:

<a attrib1="value1" attrib2="value2"/>

Jika kedua atribut (AttributeBlockName dan AttributePrefix) ditentukan seperti yang ditentukan dalam contoh XML ke JSON, struktur JSON berikut akan dibuat:

{
  "a": {
    "FOO_BLOCK": {
      "BAR_attrib1": "value1",
      "BAR_attrib2": "value2"
    }
  }
}

Jika hanya AttributeBlockName yang ditentukan, struktur JSON berikut akan dibuat:

{
    "a": {
        "FOO_BLOCK": {
            "attrib1": "value1",
            "attrib2": "value2"
        }
    }
}

Jika hanya AttributePrefix yang ditentukan, struktur JSON berikut akan dibuat:

{
    "a": {
        "BAR_attrib1": "value1",
        "BAR_attrib2": "value2"
    }
}

Jika tidak ada yang ditentukan, struktur JSON berikut akan dibuat:

{
    "a": {
        "attrib1": "value1",
        "attrib2": "value2"
    }
}

Elemen <Options>/<OutputPrefix>
<Options>/<OutputSuffix>

Gunakan elemen ini bersama-sama.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

Perhatikan contoh XML berikut:

<a>value</a>

Jika kedua atribut (OutputPrefix dan OutputSuffix) ditentukan seperti yang ditentukan dalam contoh XML ke JSON, struktur JSON berikut akan dibuat:

PREFIX_{
    "a": "value"
}_SUFFIX

Jika hanya OutputPrefix yang ditentukan, struktur JSON berikut akan dibuat:

PREFIX_{
  "a" : "value"
}

Jika hanya OutputSuffix yang ditentukan, struktur JSON berikut akan dibuat:

{
  "a" : "value"
}_SUFFIX

Jika OutputPrefix maupun OutputSuffix tidak ditentukan, struktur JSON berikut akan dibuat:

{
    "a": "value"
}

Elemen <Options>/<StripLevels>

<Options>
    <StripLevels>4</StripLevels>
</Options>

Terkadang payload XML, seperti SOAP, memiliki banyak tingkat induk yang tidak ingin Anda sertakan dalam JSON yang dikonversi. Berikut adalah contoh respons SOAP yang berisi banyak tingkat:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
          <GetCityWeatherByZIPResult>
              <State>CO</State>
              <City>Denver</City>
              <Description>Sunny</Description>
              <Temperature>62</Temperature>
          </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
  </soap:Body>
</soap:Envelope>

Ada 4 level sebelum Anda mencapai level Negara Bagian, Kota, Deskripsi, dan Suhu. Tanpa menggunakan <StripLevels>, respons JSON yang dikonversi akan terlihat seperti ini:

{
   "Envelope" : {
      "Body" : {
         "GetCityWeatherByZIPResponse" : {
            "GetCityWeatherByZIPResult" : {
               "State" : "CO",
               "City" : "Denver",
               "Description" : "Sunny",
               "Temperature" : "62"
            }
         }
      }
   }
}

Jika Anda ingin menghapus 4 tingkat pertama dalam respons JSON, Anda akan menetapkan <StripLevels>4</StripLevels>, yang akan memberi Anda JSON berikut:

{
  "State" : "CO",
  "City" : "Denver",
  "Description" : "Sunny",
  "Temperature" : "62"
}

Anda dapat menghapus level hingga elemen pertama yang berisi beberapa turunan. Apa artinya? Mari kita lihat contoh JSON yang lebih kompleks:

{
   "Envelope" : {
      "Body" : {
         "GetCityForecastByZIPResponse" : {
            "GetCityForecastByZIPResult" : {
               "ResponseText" : "City Found",
               "ForecastResult" : {
                  "Forecast" : [
                     {
                        "ProbabilityOfPrecipiation" : {
                           "Nighttime" : "00",
                           "Daytime" : 10
                        }  ...

Level 3 dalam contoh ini adalah GetCityForecastByZIPResponse, yang hanya memiliki satu turunan. Jadi, jika Anda menggunakan <StripLevels>3</StripLevels> (menghapus tiga tingkat pertama), JSON akan terlihat seperti ini:

{
   "GetCityForecastByZIPResult" : {
      "ResponseText" : "City Found",
      "ForecastResult" : {
         "Forecast" : [
            {
               "ProbabilityOfPrecipiation" : {
                  "Nighttime" : "00",
                  "Daytime" : 10
               }  ...

Perhatikan bahwa GetCityForecastByZIPResult memiliki beberapa turunan. Karena merupakan elemen pertama yang berisi beberapa turunan, Anda dapat menghapus tingkat terakhir ini menggunakan <StripLevels>4</StripLevels>, yang akan memberi Anda JSON berikut:

{
   "ResponseText" : "City Found",
   "ForecastResult" : {
      "Forecast" : [
         {
            "ProbabilityOfPrecipiation" : {
               "Nighttime" : "00",
               "Daytime" : 10
            }  ...

Karena level 4 adalah level pertama yang berisi beberapa turunan, Anda tidak dapat menghapus level yang lebih rendah dari level ini. Jika Anda menyetel tingkat strip ke 5, 6, 7, dan seterusnya, Anda akan terus mendapatkan respons di atas.

Elemen <Options>/<TreatAsArray>/<Path>

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

Kombinasi elemen ini memungkinkan Anda memastikan bahwa nilai dari dokumen XML dimasukkan ke dalam array JSON. Hal ini berguna, misalnya, saat jumlah elemen turunan dapat bervariasi (dari satu hingga beberapa), dan Anda ingin memastikan nilai selalu berada dalam array. Tindakan ini membantu menjaga kestabilan kode Anda, karena Anda bisa mendapatkan data dari array dengan cara yang sama setiap saat. Misalnya: $.teachers.teacher.studentnames[0] mendapatkan nilai nama siswa pertama dalam array, terlepas dari jumlah nilai dalam array.

Mari kita kembali ke langkah sebelumnya dan melihat perilaku default XML ke JSON, lalu pelajari cara mengontrol output menggunakan <TreatAsArray>/<Path>.

Jika dokumen XML berisi elemen dengan beberapa nilai turunan (biasanya berdasarkan skema dengan maxOccurs='unbounded' elemen), kebijakan XML ke JSON akan otomatis menempatkan nilai tersebut dalam array. Misalnya, blok XML berikut

<teacher>
    <name>teacherA</name>
    <studentnames>
        <name>student1</name>
        <name>student2</name>
    </studentnames>
</teacher>

...dikonversi menjadi JSON berikut secara otomatis tanpa konfigurasi kebijakan khusus:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}
           }
      }
}

Perhatikan bahwa kedua nama siswa dimasukkan ke dalam array.

Namun, jika hanya satu siswa yang muncul dalam dokumen XML, kebijakan XML ke JSON akan otomatis memperlakukan nilai sebagai satu string, bukan array string, seperti yang ditunjukkan dalam contoh berikut:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : "student1"
              }
          }
      }
}

Pada contoh sebelumnya, data serupa dikonversi secara berbeda, sekali sebagai array, dan sekali lagi sebagai string tunggal. Di sinilah elemen <TreatAsArray>/<Path> memungkinkan Anda mengontrol output. Misalnya, Anda dapat memastikan bahwa nama siswa selalu dimasukkan ke dalam array meskipun hanya ada satu nilai. Anda mengonfigurasi ini dengan mengidentifikasi Jalur ke elemen yang nilainya ingin Anda masukkan ke dalam array, seperti berikut:

<Options>
    <TreatAsArray>
        <Path>teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

Konfigurasi di atas akan menulis JSON seperti ini:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : ["student1"]
              }
            ]
          }
      }
}

Perhatikan bahwa student1 sekarang berada dalam array. Sekarang, terlepas dari apakah ada satu atau beberapa siswa, Anda dapat mengambilnya dari array JSON dalam kode menggunakan JSONPath berikut: $.teachers.teacher.studentnames.name[0]

Elemen <Path> juga memiliki atribut unwrap, yang dijelaskan di bagian berikutnya.

Atribut

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

Untuk contoh selengkapnya dan panduan fitur, lihat artikel Komunitas Apigee ini: Community tutorial: The TreatAsArray option in the XML to JSON policy.

<Format>

Format memberi Anda kontrol atas konversi dari XML ke JSON. Masukkan nama template yang telah ditentukan sebelumnya yang berisi kombinasi elemen Opsi tertentu yang dijelaskan dalam topik ini. Format standar mencakup: xml.com, yahoo, google, badgerFish.

Gunakan elemen <Format> atau grup <Options>. Anda tidak dapat menggunakan <Format> dan <Options> secara bersamaan.

Berikut adalah definisi Format setiap template standar.

xml.com

<RecognizeNull>true</RecognizeNull>
<TextNodeName>#text</TextNodeName>
<AttributePrefix>@</AttributePrefix>

yahoo

<RecognizeNumber>true</RecognizeNumber>
<TextNodeName>content</TextNodeName>

google

<TextNodeName>$t</TextNodeName>
<NamespaceSeparator>$</NamespaceSeparator>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>

badgerFish

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

Sintaksis elemen:

<Format>yahoo</Format>

Skema

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Example fault rule

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

Topik terkait

JSON ke XML: JSON to XML policy