سياسة JSONtoXML

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلىمستندات Apigee X. info

الأدوات المستخدمة

تحوِّل هذه السياسة الرسائل من تنسيق JavaScript Object Notation (JSON) إلى لغة الترميز القابلة للتوسيع (XML)، ما يمنحك عدة خيارات للتحكّم في طريقة تحويل الرسائل.

تكون السياسة مفيدة بشكل خاص إذا أردت تحويل الرسائل باستخدام XSL. بعد تحويل حمولة JSON إلى XML، استخدِم سياسة XSL Transform مع ورقة أنماط مخصّصة لإجراء عملية التحويل التي تحتاج إليها.

بافتراض أنّ الهدف هو تحويل طلب بتنسيق JSON إلى طلب بتنسيق XML، سيتم إرفاق السياسة بطلب Flow (على سبيل المثال، Request / ProxyEndpoint / PostFlow).

نماذج

لمناقشة مفصّلة حول التحويل بين JSON وXML، يُرجى الاطّلاع على مقالة مشكلة تحويل مصفوفة JSON إلى مصفوفة XML في عنصر الاستجابة.

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

مرجع العناصر

في ما يلي العناصر والسمات التي يمكنك ضبطها في هذه السياسة.

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

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

&lt;DisplayName&gt; عنصر

استخدِمه مع السمة name لتصنيف السياسة في إدارة خادم وكيل لواجهة المستخدم باسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>

العنصر <Source>

المتغيّر أو الطلب أو الردّ الذي يحتوي على رسالة JSON التي تريد تحويلها إلى XML.

إذا لم يتم تحديد <Source>، سيتم التعامل معه على أنّه رسالة (يتم حلّها إلى طلب عند إرفاق السياسة بطلب flow، أو ردّ عند إرفاق السياسة بردّ flow).

إذا تعذّر حلّ المتغيّر المصدر أو تم حلّه إلى نوع غير نوع الرسالة، ستعرض السياسة خطأً.

<Source>request</Source>

العنصر <OutputVariable>

يخزِّن ناتج عملية التحويل من تنسيق JSON إلى XML. عادةً ما تكون هذه القيمة هي نفسها قيمة المصدر، أي أنّه عادةً ما يتم تحويل طلب JSON إلى طلب XML.

يتم تحليل حمولة رسالة JSON وتحويلها إلى XML، ويتم ضبط عنوان HTTP Content-type للرسالة بتنسيق XML على text/xml;charset=UTF-8.

إذا لم يتم تحديد OutputVariable، يتم التعامل مع source على أنّه OutputVariable. على سبيل المثال، إذا كان source هو request، يتم ضبط OutputVariable تلقائيًا على request.

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

يحدّد ما إذا كان سيتم حذف مساحة اسم XML من الناتج. القيمة التلقائية هي false ، ما يعني تضمين مساحة الاسم في الناتج.

على سبيل المثال، يضبط الإعداد التالي السياسة على حذف مساحة الاسم:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

لا يتيح JSON مساحات الأسماء، بينما غالبًا ما تتطلب مستندات XML مساحات الأسماء. NamespaceBlockName تتيح لك تحديد سمة JSON تعمل كمصدر لتعريف مساحة اسم في XML الذي تنتجه السياسة. (يعني ذلك أنّ مصدر JSON يجب أن يوفّر سمة يمكن ربطها بمساحة اسم يتوقعها التطبيق الذي يستهلك XML الناتج).

على سبيل المثال، تشير الإعدادات التالية:

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

إلى أنّ هناك سمة باسم #namespaces في مصدر JSON التي تحتوي على مساحة اسم واحدة على الأقل تم تحديدها كمساحة الاسم التلقائية. على سبيل المثال:

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

يتم تحويلها إلى:

<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> يحدّد اسم العنصر الجذر عند التحويل من JSON، الذي لا يحتوي على عنصر جذر باسم، إلى XML.

على سبيل المثال، إذا كان JSON يظهر على النحو التالي:

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

وتم ضبط <ObjectRootElementName> على النحو التالي:

<ObjectRootElementName>Root</ObjectRootElementName>

يظهر XML الناتج على النحو التالي:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elements

<AttributeBlockName> تتيح لك تحديد متى يتم تحويل عناصر JSON إلى سمات XML (بدلاً من عناصر XML).

على سبيل المثال، يحوّل الإعداد التالي السمات داخل كائن باسم #attrs إلى سمات XML:

<AttributeBlockName>#attrs</AttributeBlockName>

كائن JSON التالي:

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

يتم تحويله إلى بنية XML التالية:

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

<AttributePrefix> يحوّل السمة التي تبدأ بالبادئة المحدّدة إلى سمات XML. إذا تم ضبط بادئة السمة على @، على سبيل المثال:

<AttributePrefix>@</AttributePrefix>

يتم تحويل كائن JSON التالي:

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

 }
}

إلى بنية XML التالية:

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

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> element

يحوّل مصفوفة JSON إلى قائمة بعناصر XML بأسماء العناصر الرئيسية والفرعية المحدّدة.

على سبيل المثال، تشير الإعدادات التالية:

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

إلى تحويل مصفوفة JSON التالية:

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

إلى بنية XML التالية:

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

<Options>/<Indent>

يحدّد ما إذا كان سيتم وضع مسافة بادئة لناتج XML. القيمة التلقائية هي false ، ما يعني عدم وضع مسافة بادئة.

على سبيل المثال، يضبط الإعداد التالي السياسة على وضع مسافة بادئة للناتج:

<Indent>true</Indent>

إذا كان إدخال JSON بالتنسيق التالي:

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

يكون الناتج بدون وضع مسافة بادئة على النحو التالي:

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

عند تفعيل وضع المسافة البادئة، يكون الناتج على النحو التالي:

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

<Options>/<TextNodeName> element

يحوّل سمة JSON إلى عقدة نص XML بالاسم المحدّد. على سبيل المثال، يشير الإعداد التالي:

<TextNodeName>age</TextNodeName>

إلى تحويل JSON هذا:

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

إلى بنية XML هذه:

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

إذا لم يتم تحديد TextNodeName، يتم إنشاء XML باستخدام الإعداد التلقائي لعقدة نص:

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

<Options>/<NullValue> element

يشير إلى قيمة فارغة. القيمة التلقائية هي NULL.

على سبيل المثال، يشير الإعداد التالي:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

إلى عنصر XML التالي:

<person></person>

إذا لم يتم تحديد أي قيمة (أو قيمة أخرى غير I_AM_NULL) للقيمة الفارغة، يتم تحويل الحمولة نفسها إلى:

<person>I_AM_NULL</person>

<Options>/<InvalidCharsReplacement> element

للمساعدة في معالجة XML غير صالح قد يسبب مشاكل في المحلّل، يستبدل هذا الإعداد أي عناصر JSON تنتج XML غير صالح بالسلسلة. على سبيل المثال، يشير الإعداد التالي:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

إلى تحويل كائن JSON هذا

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

إلى بنية XML هذه:

<First_Name>John<First_Name>

ملاحظات حول الاستخدام

في سيناريو الوساطة النموذجي، غالبًا ما يتم إقران سياسة JSON إلى XML في تدفق الطلب الوارد بسياسة XMLtoJSON في تدفق الردّ الصادر. من خلال الجمع بين السياسات بهذه الطريقة، يمكن عرض واجهة برمجة تطبيقات JSON للخدمات التي لا تتوافق إلا مع XML بشكل أساسي.

من المفيد غالبًا تطبيق سياسة JSON إلى XML التلقائية (الفارغة) وإضافة عناصر الإعداد بشكل متكرّر حسب الحاجة.

في السيناريوهات التي تستهلك فيها تطبيقات عميل متنوعة واجهات برمجة التطبيقات، والتي قد تتطلب JSON وXML، يمكن ضبط تنسيق الردّ ديناميكيًا من خلال ضبط سياسات JSON إلى XML وXML إلى JSON لتنفيذها بشكل مشروط. يمكنك الاطّلاع على متغيّرات التدفق والشروط للحصول على مثال على تنفيذ هذا السيناريو.

المخططات

مرجع الأخطاء

يصف هذا القسم رموز الخطأ ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تم ضبطها من خلال Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. من المهم معرفة هذه المعلومات إذا كنت تضع قواعد خطأ التعامل مع الأخطاء. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على ما تحتاج إلى معرفته حول أخطاء السياسة والتعامل مع المعالجة والأخطاء.

أخطاء بيئة التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

أخطاء النشر

بلا عُري

متغيّرات الأخطاء

يتم ضبط هذه المتغيّرات عند حدوث خطأ في بيئة التشغيل. يمكنك الاطّلاع على مقالة ما تحتاج إلى معرفته للحصول على مزيد من المعلومات. حول أخطاء السياسة.

مثال على استجابة الخطأ

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

مثال على قاعدة الخطأ

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

مواضيع ذات صلة

• XML إلى JSON: سياسة XML إلى JSON
• تحويل XSL: سياسة XSL Transform