Kebijakan XMLtoJSON

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

Apa

Kebijakan ini mengonversi pesan dari format Extensible Markup Language (XML) menjadi JavaScript Object Notation (JSON), yang memberi Anda beberapa opsi untuk mengontrol cara pesan dikonversi.

Dengan asumsi bahwa intent adalah untuk mengonversi respons berformat XML menjadi respons berformat JSON kebijakan tersebut akan disertakan ke Alur respons (misalnya, Respons / ProxyEndpoint / PostFlow).

Tentang

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

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

Contoh

Untuk diskusi mendetail tentang konversi antara JSON dan XML, lihat http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.

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

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi di 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>

<XMLtoJSON> atribut

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

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

<DisplayName> elemen

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

<DisplayName>Policy Display Name</DisplayName>

<Source> elemen

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

Header jenis Konten HTTP pesan sumber harus ditetapkan ke application/xml, jika tidak, kebijakan ini tidak akan diterapkan.

Jika <Source> tidak ditentukan, maka akan diperlakukan sebagai pesan (yang me-resolve untuk meminta saat kebijakan dilampirkan ke alur permintaan, atau respons saat kebijakan dilampirkan terhadap alur respons).

Jika variabel sumber tidak dapat di-resolve, atau di-resolve menjadi jenis bukan pesan, kebijakan tersebut menampilkan error.

<Source>response</Source>

<OutputVariable> elemen

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

Payload pesan XML akan diuraikan dan dikonversi menjadi JSON, serta jenis Konten HTTP header pesan berformat XML disetel ke application/json.

Jika OutputVariable tidak ditentukan, source diperlakukan sebagai OutputVariable. Misalnya, jika source adalah response, lalu OutputVariable secara default menjadi 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 sekaligus <Format>.

<Options> diperlukan jika <Format> tidak digunakan.

<Options>/<RecognizeNumber> elemen

Jika true (benar), 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, lakukan konversi menjadi:

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

Jika false, lakukan konversi menjadi:

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

<Options>/<RecognizeBoolean> elemen

Memungkinkan konversi mempertahankan nilai boolean/salah (true) daripada mengubahnya menjadi {i>string<i}.

<RecognizeBoolean>true</RecognizeBoolean>

Untuk contoh XML berikut:

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

Jika true, lakukan konversi menjadi:

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

Jika false, lakukan konversi menjadi:

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

&lt;Options&gt;/&lt;RecognizeNull&gt; elemen

Memungkinkan Anda mengonversi nilai kosong menjadi nilai null.

<RecognizeNull>true</RecognizeNull>

Untuk XML berikut:

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

Jika true, lakukan konversi menjadi:

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

Jika false, lakukan konversi menjadi:

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

&lt;Options&gt;/&lt;NullValue&gt; elemen

Menunjukkan nilai yang seharusnya menjadi target nilai null yang dikenali dalam pesan sumber dikonversi. Secara default, nilainya adalah null. Opsi ini hanya berlaku jika RecognizeNull benar.

<NullValue>not-present</NullValue>

&lt;Options&gt;/&lt;NamespaceBlockName&gt;
&lt;Options&gt;/&lt;DefaultNamespaceNodeName&gt;
&lt;Options&gt;/&lt;NamespaceSeparator&gt; elemen

Gunakan elemen-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 ditetapkan sebagai #namespaces, &, dan ***, masing-masing, struktur JSON berikut akan dibuat:

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

&lt;Options&gt;/&lt;TextAlwaysAsProperty&gt;
&lt;Options&gt;/&lt;TextNodeName&gt; elemen

Gunakan elemen-elemen ini bersama-sama.

Jika ditetapkan ke true, konten elemen XML akan dikonversi menjadi string saat ini.

<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 ditetapkan sebagai TEXT, struktur JSON berikut akan dibuat:

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

Jika TextAlwaysAsProperty disetel ke false dan TextNodeName ditetapkan sebagai TEXT, struktur JSON berikut adalah dibuat:

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

&lt;Options&gt;/&lt;AttributeBlockName&gt;
&lt;Options&gt;/&lt;AttributePrefix&gt; elemen

Gunakan elemen-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) ditetapkan seperti yang ditetapkan dalam contoh XML ke JSON, struktur JSON berikut akan dihasilkan:

{
  "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"
    }
}

&lt;Options&gt;/&lt;OutputPrefix&gt;
&lt;Options&gt;/&lt;OutputSuffix&gt; elemen

Gunakan elemen-elemen ini bersama-sama.

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

Perhatikan contoh XML berikut:

<a>value</a>

Jika kedua atribut (OutputPrefix dan OutputSuffix) ditetapkan sebagaimana didefinisikan dalam contoh XML ke JSON, struktur JSON berikut akan dihasilkan:

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 atau OutputSuffix tidak ditentukan, hal berikut Struktur JSON dibuat:

{
    "a": "value"
}

&lt;Options&gt;/&lt;StripLevels&gt; elemen

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

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

<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 tingkat sebelum Anda mencapai tingkat 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 tersebut dalam respons JSON, Anda perlu <StripLevels>4</StripLevels>, yang akan memberi Anda info berikut JSON:

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

Anda dapat menghilangkan level hingga elemen pertama yang berisi beberapa turunan. Fungsi maksudnya? 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 anak. Jadi, jika Anda menggunakan <StripLevels>3</StripLevels> (hapus 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 ini adalah elemen pertama yang berisi beberapa turunan, Anda dapat membongkar level terakhir ini menggunakan <StripLevels>4</StripLevels>, yang akan memberi Anda JSON:

{
   "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 mana pun lebih rendah dari ini. Jika Anda mengatur tingkat strip ke 5, 6, 7, dan seterusnya, Anda akan terus mendapatkan respons di atas.

&lt;Options&gt;/&lt;TreatAsArray&gt;/&lt;Path&gt; elemen

<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 JSON . Hal ini berguna, misalnya, ketika jumlah elemen turunan dapat bervariasi (dari satu hingga multi), dan Anda ingin memastikan nilainya selalu dalam array. Melakukan hal ini membantu menjaga stabil, karena Anda bisa mendapatkan data dari array dengan cara yang sama setiap saat. Sebagai contoh: $.teachers.teacher.studentnames[0] mendapatkan nilai nama siswa pertama dalam array tanpa memperhitungkan jumlah nilai dalam array.

Mari kita mundur selangkah dan melihat perilaku default XML ke JSON, lalu jelajahi cara mengontrol output menggunakan <TreatAsArray>/<Path>.

Jika dokumen XML berisi elemen dengan beberapa nilai turunan (biasanya didasarkan pada skema dengan maxOccurs='unbounded' elemen), kebijakan XML ke JSON akan otomatis menempatkan nilai-nilai tersebut di {i>array<i}. Misalnya, blok XML berikut

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

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

{
  "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 string tunggal, bukan array string, seperti yang ditunjukkan dalam contoh:

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

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

<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 di array. Kini, terlepas dari apakah ada satu atau beberapa Anda, Anda dapat mengambilnya dari array JSON dalam kode Anda 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 dan panduan fitur lainnya, lihat artikel Komunitas Apigee ini: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html.

&lt;Format&gt;

Format memberi Anda kontrol atas konversi dari XML ke JSON. Masukkan nama {i>template<i} yang berisi kombinasi tertentu dari elemen Opsi 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>.

Berikut adalah definisi Format dari setiap template yang telah ditentukan sebelumnya.

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 ke XML kebijakan