Kebijakan JSONtoXML

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

Apa

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

Kebijakan ini sangat berguna jika Anda ingin mengubah pesan menggunakan XSL. Setelah mengonversi payload JSON ke XML, gunakan kebijakan Transformasi XSL dengan lembar gaya kustom untuk melakukan transformasi yang Anda butuhkan.

Dengan asumsi bahwa tujuannya adalah mengonversi permintaan berformat JSON menjadi permintaan berformat XML, kebijakan akan dilampirkan ke Flow permintaan (misalnya, Request / ProxyEndpoint / PostFlow).

Contoh

Untuk pembahasan mendetail tentang konversi antara JSON dan XML, lihat Masalah konversi array JSON ke array XML dalam objek respons.

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

Referensi elemen

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

<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1">
    <DisplayName>JSON to XML 1</DisplayName>
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
    <Options>
        <OmitXmlDeclaration>false</OmitXmlDeclaration>
        <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
        <NamespaceSeparator>:</NamespaceSeparator>
        <AttributeBlockName>#attrs</AttributeBlockName>
        <AttributePrefix>@</AttributePrefix>
        <ObjectRootElementName>Root</ObjectRootElementName>
        <ArrayRootElementName>Array</ArrayRootElementName>
        <ArrayItemElementName>Item</ArrayItemElementName>
        <Indent>false</Indent>
        <TextNodeName>#text</TextNodeName>
        <NullValue>I_AM_NULL</NullValue>
        <InvalidCharsReplacement>_</InvalidCharsReplacement>
    </Options>
</JSONToXML>

Atribut <JSONToXML>

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 JSON yang ingin Anda konversi ke XML.

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

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

<Source>request</Source>

Elemen <OutputVariable>

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

Payload pesan JSON diuraikan dan dikonversi menjadi XML, dan header Content-type HTTP dari pesan berformat XML ditetapkan ke text/xml;charset=UTF-8.

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

<OutputVariable>request</OutputVariable>

Elemen <Options>/<OmitXmlDeclaration>

Menentukan untuk menghapus namespace XML dari output. Nilai defaultnya adalah false , yang berarti menyertakan namespace dalam output.

Misalnya, setelan berikut mengonfigurasi kebijakan untuk menghapus namespace:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

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

JSON tidak memiliki dukungan untuk namespace, sedangkan dokumen XML sering kali memerlukannya. NamespaceBlockName memungkinkan Anda menentukan properti JSON yang berfungsi sebagai sumber definisi namespace dalam XML yang dihasilkan oleh kebijakan. (Artinya, JSON sumber harus menyediakan properti yang dapat dipetakan ke namespace yang diharapkan oleh aplikasi yang menggunakan XML yang dihasilkan.)

Misalnya, setelan berikut:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

menunjukkan bahwa properti bernama #namespaces ada dalam JSON sumber yang berisi setidaknya satu namespace yang ditetapkan sebagai default. Contoh:

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

dikonversi menjadi:

<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers">
  <person>John Smith</person>
  <exp:person>Pedro Cabral</exp:person>
</population>

Elemen <Options>/<ObjectRootElementName>

<ObjectRootElementName> menentukan nama elemen root saat Anda mengonversi dari JSON, yang tidak memiliki elemen root bernama, ke XML.

Misalnya, jika JSON muncul sebagai:

{
  "abc": "123",
  "efg": "234"
}

Dan Anda menetapkan <ObjectRootElementName> sebagai:

<ObjectRootElementName>Root</ObjectRootElementName>

XML yang dihasilkan akan muncul sebagai:

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

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

<AttributeBlockName> memungkinkan Anda menentukan kapan elemen JSON dikonversi menjadi atribut XML (bukan elemen XML).

Misalnya, setelan berikut mengonversi properti di dalam objek bernama #attrs menjadi atribut XML:

<AttributeBlockName>#attrs</AttributeBlockName>

Objek JSON berikut:

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },
        "occupation" : "explorer",
    }
}

dikonversi menjadi struktur XML berikut:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<AttributePrefix> mengonversi properti yang dimulai dengan awalan yang ditentukan menjadi atribut XML. Jika awalan atribut ditetapkan ke @, misalnya:

<AttributePrefix>@</AttributePrefix>

Mengonversi objek JSON berikut:

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

menjadi struktur XML berikut:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<Options>/<ArrayRootElementName>
Elemen <Options>/<ArrayItemElementName>

Mengonversi array JSON menjadi daftar elemen XML dengan nama elemen induk dan turunan yang ditentukan.

Misalnya, setelan berikut:

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

mengonversi array JSON berikut:

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

menjadi struktur XML berikut:

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

Elemen <Options>/<Indent>

Menentukan untuk membuat indentasi pada output XML. Nilai defaultnya adalah false yang berarti tidak membuat indentasi.

Misalnya, setelan berikut mengonfigurasi kebijakan untuk membuat indentasi pada output:

<Indent>true</Indent>

Jika input JSON dalam bentuk:

{"n": [1, 2, 3] }

Maka output tanpa indentasi adalah:

<Array><n>1</n><n>2</n><n>3</n></Array>

Dengan indentasi diaktifkan, outputnya adalah:

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

Elemen <Options>/<TextNodeName>

Mengonversi properti JSON menjadi node teks XML dengan nama yang ditentukan. Misalnya, setelan berikut:

<TextNodeName>age</TextNodeName>

mengonversi JSON ini:

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

ke struktur XML ini:

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

Jika TextNodeName tidak ditentukan, XML akan dibuat menggunakan setelan default untuk node teks:

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

Elemen <Options>/<NullValue>

Menunjukkan nilai null. Secara default, nilainya adalah NULL.

Misalnya, setelan berikut:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

ke elemen XML berikut:

<person></person>

Jika tidak ada nilai (atau nilai selain I_AM_NULL) yang ditentukan untuk nilai Null, payload yang sama akan dikonversi menjadi:

<person>I_AM_NULL</person>

Elemen <Options>/<InvalidCharsReplacement>

Untuk membantu menangani XML yang tidak valid yang dapat menyebabkan masalah pada parser, setelan ini mengganti elemen JSON apa pun yang menghasilkan XML yang tidak valid dengan string. Misalnya, setelan berikut:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Mengonversi objek JSON ini

{
    "First%%%Name": "John"
}

ke struktur XML ini:

<First_Name>John<First_Name>

Catatan penggunaan

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

Sering kali berguna untuk menerapkan kebijakan JSON ke XML default (kosong) dan menambahkan elemen konfigurasi secara berulang sesuai kebutuhan.

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

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

None.

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": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

Topik terkait

• XML to JSON: XML to JSON kebijakan
• Transformasi XSL: Kebijakan Transformasi XSL