سياسة 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 لتنفيذها بشكل مشروط. يمكنك الاطّلاع على متغيّرات التدفق والشروط للحصول على مثال على تنفيذ هذا السيناريو.

المخططات

مرجع الأخطاء

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>

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

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