Kebijakan JSONtoXML

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

ikon kebijakan

Apa

Kebijakan ini mengonversi pesan dari format JavaScript Object Notation (JSON) menjadi extensible markup language (XML), yang memberi Anda 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 perlukan.

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua pengguna perlu mengetahui tentang kebijakan dan jenis lingkungan. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.

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

Sampel

Untuk diskusi mendetail, lihat Mengonversi antara XML dan JSON dengan Apigee: hal yang perlu Anda ketahui.

Mengonversi permintaan

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

Konfigurasi ini menggunakan pesan permintaan berformat JSON sebagai sumber, lalu membuat pesan berformat XML yang diisi dalam OutputVariable request. Apigee otomatis menggunakan konten variabel ini sebagai pesan untuk langkah pemrosesan berikutnya.

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 sama untuk semua elemen induk kebijakan:

Atribut Deskripsi Default Kehadiran
name

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

 T/A Diperlukan
continueOnError

Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.

 true Opsional
async

Atribut ini sudah tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

Elemen <Source>

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

Jika <Source> tidak ditentukan, pesan akan diperlakukan sebagai pesan (yang di-resolve untuk meminta 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>
Default permintaan atau respons, ditentukan oleh tempat kebijakan ditambahkan ke alur proxy API
Kehadiran Opsional
Type pesan

Elemen <OutputVariable>

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

Payload pesan JSON diuraikan dan dikonversi menjadi XML, dan header Content-type HTTP 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>
Default permintaan atau respons, ditentukan oleh tempat kebijakan ditambahkan ke alur proxy API
Kehadiran Elemen ini bersifat wajib jika variabel yang ditentukan dalam elemen <Source> merupakan string jenis.
Type pesan

<Options>/<OmitXmlDeclaration>

Menentukan untuk menghilangkan baris deklarasi XML dari output. Baris deklarasi XML dapat muncul secara opsional di bagian atas dokumen XML. Contoh umumnya terlihat seperti ini: 

<?xml version="1.0" encoding="UTF-8"?>

Dalam beberapa kasus, penting untuk menghindari penyertaan baris seperti itu dalam output kebijakan ini. Salah satu contoh yang bagus adalah jika Anda berencana untuk menyematkan output kebijakan ini sebagai fragmen ke dalam dokumen XML yang lebih besar. Karena deklarasi harus muncul hanya sekali dalam dokumen dan hanya di bagian atas dokumen, baris deklarasi XML dalam fragmen XML harus disembunyikan dalam hal ini.

Nilai default untuk opsi ini adalah false, yang berarti kebijakan akan menyertakan baris deklarasi XML dalam output. Setelan berikut akan mengonfigurasi kebijakan untuk menghapus Deklarasi XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Tidak ada cara untuk membentuk atau memengaruhi konten baris deklarasi XML melalui konfigurasi kebijakan ini. Kebijakan ini selalu menghasilkan teks yang dienkode UTF-8, dan selalu menggunakan XML versi 1.0, dan baris deklarasi, jika disertakan, akan mencerminkan hal tersebut.

<Opsi>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
elemen <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 tersebut. (Artinya, JSON sumber harus menyediakan properti yang dapat dipetakan ke dalam namespace yang diharapkan oleh aplikasi yang menggunakan XML yang dihasilkan.)

Misalnya, setelan berikut:

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

menunjukkan bahwa ada properti bernama #namespaces di 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>

<Opsi>/<ObjectRootElementName>

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

Misalnya, jika JSON muncul sebagai:

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

Selanjutnya tetapkan <ObjectRootElementName> sebagai:

<ObjectRootElementName>Root</ObjectRootElementName>

XML yang dihasilkan akan muncul sebagai:

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

<Opsi>/<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 ke 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",

 }
}

ke struktur XML berikut:

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

<Opsi>/<ArrayRootElementName>
elemen <Options>/<ArrayItemElementName>

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

Misalnya, setelan berikut:

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

mengonversi array JSON berikut:

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

ke dalam struktur XML berikut:

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

<Opsi>/<Indent>

Menentukan indentasi output XML. Nilai defaultnya adalah false yang berarti jangan mengindentasi.

Misalnya, setelan berikut mengonfigurasi kebijakan untuk mengindentasi output:

<Indent>true</Indent>

Jika input JSON dalam bentuk:

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

Outputnya tanpa intdentasi adalah:

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

Setelah 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 dihasilkan, 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>
Mengonversi objek JSON berikut: 
{"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 tidak valid yang dapat menyebabkan masalah pada parser, setelan ini menggantikan elemen JSON yang menghasilkan XML tidak valid dengan string tersebut. 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 kali dipasangkan dengan kebijakan XMLtoJSON pada alur respons keluar. Dengan menggabungkan kebijakan seperti ini, JSON API dapat diekspos untuk layanan yang secara native hanya mendukung XML.

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

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

Skema

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code HTTP status Cause Fix
steps.jsontoxml.ExecutionFailed 500 The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed.
steps.jsontoxml.InCompatibleTypes 500 This error occurs if the type of the variable defined in the <Source> element and the <OutputVariable> element are not the same. It is mandatory that the type of the variables contained within the <Source> element and the <OutputVariable> element matches. The valid types are message and string.
steps.jsontoxml.InvalidSourceType 500 This error occurs if the type of the variable used to define the <Source> element is invalid. The valid types of variable are message and string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 This error occurs if the variable specified in the <Source> element of the JSON to XML Policy is of type string and the <OutputVariable> element is not defined. The <OutputVariable> element is mandatory when the variable defined in the <Source> element is of type string.
steps.jsontoxml.SourceUnavailable 500 This error occurs if the message variable specified in the <Source> element of the JSON to XML policy is either:
  • Out of scope (not available in the specific flow where the policy is being executed) or
  • Can't be resolved (is not defined)

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.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. jsontoxml.JSON-to-XML-1.failed = true

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