Kebijakan JSONtoXML

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

ikon kebijakan

Apa

Kebijakan ini mengonversi pesan dari format JavaScript Object Notation (JSON) ke 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 menjadi XML, gunakan kebijakan XSL Transform dengan lembar gaya kustom untuk melakukan transformasi yang Anda perlukan.

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

Dengan asumsi bahwa tujuannya adalah mengonversi permintaan berformat JSON menjadi permintaan berformat XML, kebijakan akan dilampirkan ke Flow permintaan (misalnya, Permintaan / 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 di OutputVariable request. Apigee secara 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 umum 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.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

 T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan.

Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.

 benar Opsional
async

Atribut ini tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami 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 tidak ditentukan, <Source> akan diperlakukan sebagai pesan (yang me-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>
Default permintaan atau respons, yang ditentukan oleh tempat kebijakan ditambahkan ke alur proxy API
Kehadiran Opsional
Jenis message

Elemen <OutputVariable>

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

Payload pesan JSON diuraikan dan dikonversi menjadi XML, dan header Jenis konten 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, OutputVariable akan ditetapkan secara default ke request.

<OutputVariable>request</OutputVariable>
Default permintaan atau respons, yang ditentukan oleh tempat kebijakan ditambahkan ke alur proxy API
Kehadiran Elemen ini wajib diisi jika variabel yang ditentukan dalam elemen <Source> berjenis string.
Jenis message

<Options>/<OmitXmlDeclaration>

Menentukan untuk menghapus 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 tersebut dalam output kebijakan ini. Salah satu contoh yang baik adalah jika Anda berencana menyematkan output kebijakan ini sebagai fragmen ke dalam dokumen XML yang lebih besar. Karena deklarasi hanya boleh muncul sekali dalam dokumen, dan hanya di bagian atas dokumen, dalam hal ini, Anda harus menyembunyikan baris deklarasi XML dalam fragmen XML.

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 mencerminkannya.

<Options>/<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. (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 di JSON sumber yang berisi minimal 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>

<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",

 }
}

ke 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"
]

ke dalam struktur XML berikut:

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

<Options>/<Indent>

Menentukan untuk membuat indent pada output XML. Nilai defaultnya adalah false, yang berarti jangan indentasi.

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

<Indent>true</Indent>

Jika input JSON dalam bentuk:

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

Kemudian, 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>
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 akan mengganti elemen JSON yang menghasilkan XML 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 standar, kebijakan JSON ke XML pada alur permintaan masuk sering kali dipasangkan dengan kebijakan XMLtoJSON pada alur respons keluar. Dengan menggabungkan kebijakan dengan cara ini, JSON API dapat diekspos untuk layanan yang secara native hanya mendukung XML.

Sering kali berguna untuk menerapkan kebijakan JSON default (kosong) ke XML dan menambahkan elemen konfigurasi secara iteratif 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 dieksekusi secara kondisional. Lihat Variabel dan kondisi alur untuk penerapan skenario ini.

Skema

Referensi error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kerusakan Status HTTP Penyebab Perbaiki
steps.jsontoxml.ExecutionFailed 500 Payload input (JSON) kosong atau input (JSON) yang diteruskan ke kebijakan JSON ke XML tidak valid atau salah format.
steps.jsontoxml.InCompatibleTypes 500 Error ini terjadi jika jenis variabel yang ditentukan dalam elemen <Source> dan elemen <OutputVariable> tidak sama. Jenis variabel yang terdapat dalam elemen <Source> dan elemen <OutputVariable> harus cocok. Jenis yang valid adalah message dan string.
steps.jsontoxml.InvalidSourceType 500 Error ini terjadi jika jenis variabel yang digunakan untuk menentukan elemen <Source> tidak valid. Jenis variabel yang valid adalah message dan string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 Error ini terjadi jika variabel yang ditentukan dalam elemen <Source> dari Kebijakan JSON ke XML berjenis string dan elemen <OutputVariable> tidak ditentukan. Elemen <OutputVariable> bersifat wajib jika variabel yang ditentukan dalam elemen <Source> berjenis string.
steps.jsontoxml.SourceUnavailable 500 Error ini terjadi jika variabel message yang ditentukan dalam elemen <Source> kebijakan JSON ke XML adalah:
  • Di luar cakupan (tidak tersedia dalam alur tertentu tempat kebijakan dijalankan) atau
  • Tidak dapat diselesaikan (tidak ditentukan)

Error saat deployment

Tidak ada.

Variabel error

Variabel ini ditetapkan saat error runtime terjadi. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama kerusakan adalah bagian terakhir dari kode kerusakan. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. jsontoxml.JSON-to-XML-1.failed = true

Contoh respons error

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Contoh aturan error

<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