Halaman ini diterjemahkan oleh Cloud Translation API.

Kebijakan JSONtoXML

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Apa

Kebijakan ini mengonversi pesan dari format JavaScript Object Notation (JSON) menjadi dapat diperluas bahasa markup (XML), yang memberi Anda beberapa opsi untuk mengontrol cara pesan dikonversi.

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

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

Catatan: Header Jenis konten HTTP pesan sumber harus ditetapkan ke application/json, jika tidak, kebijakan ini tidak diterapkan, artinya dilewati selama pemrosesan.

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

Sampel

Untuk diskusi terperinci, 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 sebuah Pesan berformat XML yang diisi dalam OutputVariable request. Apigee secara otomatis menggunakan isi variabel ini sebagai pesan untuk langkah pemrosesan berikutnya.

Referensi elemen

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

<JSONToXML> atribut

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: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani kesalahan dalam alur saat ini	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

Default	T/A Jika Anda menghapus elemen ini, nilai atribut `name` kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.

Kehadiran Opsional

Jenis String

<Source> elemen

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

Catatan: Header Jenis konten HTTP pesan sumber harus ditetapkan ke application/json, jika tidak, kebijakan tidak diterapkan, yang berarti akan dilewati selama pemrosesan.

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>request</Source>

Default	permintaan atau respons, yang ditentukan oleh tempat kebijakan ditambahkan ke alur proxy API
Kehadiran	Opsional
Jenis	message

<OutputVariable> elemen

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

Payload pesan JSON akan diuraikan dan dikonversi menjadi XML, serta jenis Konten HTTP header pesan berformat XML disetel ke text/xml;charset=UTF-8.

Jika OutputVariable tidak ditentukan, source diperlakukan sebagai OutputVariable. Misalnya, jika source adalah request, lalu OutputVariable secara default menjadi request.

<OutputVariable>request</OutputVariable>

Default	permintaan atau respons, yang ditentukan oleh tempat kebijakan ditambahkan ke alur proxy API
Kehadiran	Elemen ini bersifat wajib jika variabel yang ditentukan dalam elemen `<Source>` merupakan string jenis.
Jenis	message

<Options>/<OmitXmlDeclaration>

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

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

Dalam beberapa kasus, sebaiknya jangan sertakan baris seperti itu dalam output kebijakan ini. Salah satu contoh yang baik adalah jika Anda berencana untuk menyematkan {i>output<i} kebijakan ini sebagai menjadi dokumen XML yang lebih besar. Karena deklarasi harus muncul hanya sekali di dalam dokumen, dan hanya di bagian atas dokumen, dalam untuk menyembunyikan baris deklarasi XML dalam fragmen XML.

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Tidak ada cara untuk membentuk atau memengaruhi konten baris deklarasi XML melalui elemen konfigurasi kebijakan ini. Kebijakan ini selalu menghasilkan teks berenkode UTF-8, dan selalu menggunakan XML versi 1.0, dan baris deklarasi, jika disertakan, akan mencerminkannya.

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elemen

JSON tidak mendukung namespace, sedangkan dokumen XML biasanya memerlukannya. NamespaceBlockName memungkinkan Anda menentukan properti JSON yang berfungsi sebagai sumber namespace dalam XML yang dihasilkan oleh kebijakan. (Ini berarti bahwa JSON sumber harus menyediakan properti yang bisa 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 properti yang disebut #namespaces ada 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>

<Options>/<ObjectRootElementName>

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

Misalnya, jika JSON ditampilkan sebagai:

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

Setel <ObjectRootElementName> sebagai:

<ObjectRootElementName>Root</ObjectRootElementName>

XML yang dihasilkan akan muncul sebagai:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elemen

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

Misalnya, setelan berikut mengonversi properti di dalam objek bernama #attrs ke dalam 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 ke dalam 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>
<Options>/<ArrayItemElementName> elemen

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

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 mengindentasi output XML. Nilai defaultnya adalah false artinya tidak mengindentasi.

Misalnya, setelan berikut akan mengonfigurasi kebijakan untuk mengindentasi output:

<Indent>true</Indent>

Jika input JSON berbentuk:

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

Outputnya tanpa intdentasi adalah:

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

Dengan mengaktifkan indentasi, output-nya adalah:

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

<Options>/<TextNodeName> elemen

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>

<Options>/<NullValue> elemen

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>

<Options>/<InvalidCharsReplacement> elemen

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

<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 ini, sebuah JSON API dapat diekspos untuk layanan yang secara native hanya mendukung XML.

Akan sangat berguna jika Anda menerapkan JSON default (kosong) ke kebijakan XML dan menambahkan elemen konfigurasi sesuai kebutuhan.

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

Skema

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan	Status HTTP	Penyebab
`steps.jsontoxml.ExecutionFailed`	`500`	Payload input (JSON) kosong atau input (JSON) yang diteruskan ke kebijakan JSON ke XML tidak valid atau memiliki format yang salah.
`steps.jsontoxml.InCompatibleTypes`	`500`	Error ini terjadi jika jenis variabel yang ditentukan dalam elemen `<Source>` dan elemen `<OutputVariable>` tidak sama. Jenis variabel yang ada 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 menetapkan 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>` Kebijakan JSON ke XML adalah string jenis dan elemen `<OutputVariable>` tidak ditentukan. Elemen `<OutputVariable>` bersifat wajib jika variabel yang ditentukan dalam elemen `<Source>` adalah string jenis.
`steps.jsontoxml.SourceUnavailable`	`500`	Error ini terjadi jika variabel message yang ditentukan dalam elemen `<Source>` dari kebijakan JSON ke XML adalah: Di luar cakupan (tidak tersedia dalam alur spesifik tempat kebijakan dijalankan) atau Tidak dapat diselesaikan (tidak ditentukan)

Error saat deployment

Tidak ada.

Variabel kesalahan

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

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

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menjebak bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena bisa berubah.

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

Contoh aturan kesalahan

<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 ke JSON: Kebijakan XMLtoJSON
Transformasi XSL: Kebijakan XSLTransform

Kebijakan JSONtoXML

Apa

Sampel

Mengonversi permintaan

Referensi elemen

&lt;JSONToXML&gt; atribut

Elemen <DisplayName>

&lt;Source&gt; elemen

&lt;OutputVariable&gt; elemen

&lt;Options&gt;/&lt;OmitXmlDeclaration&gt;

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

&lt;Options&gt;/&lt;ObjectRootElementName&gt;

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

&lt;Options&gt;/&lt;ArrayRootElementName&gt; &lt;Options&gt;/&lt;ArrayItemElementName&gt; elemen

&lt;Options&gt;/&lt;Indent&gt;

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

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

&lt;Options&gt;/&lt;InvalidCharsReplacement&gt; elemen

Catatan penggunaan

Skema

Referensi error

Error runtime

Error saat deployment

Variabel kesalahan

Contoh respons error

Contoh aturan kesalahan

Topik terkait

<JSONToXML> atribut

<Source> elemen

<OutputVariable> elemen

<Options>/<OmitXmlDeclaration>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elemen

<Options>/<ObjectRootElementName>

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elemen

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

<Options>/<Indent>

<Options>/<TextNodeName> elemen

<Options>/<NullValue> elemen

<Options>/<InvalidCharsReplacement> elemen