سياسة JSONtoXML

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

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

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

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

بافتراض أنّ الهدف هو تحويل طلب بتنسيق JSON إلى طلب بتنسيق XML، سيتم إرفاق السياسة بتدفق طلب (على سبيل المثال، 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>، سيتم التعامل معه كرسالة (يتم تحويلها إلى طلب عندما تكون السياسة مرتبطة بسير عمل الطلب، أو استجابة عندما تكون السياسة مرتبطة بسير عمل الاستجابة).

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

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

لا يتوافق 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>

تتيح لك <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>

يحوّل مصفوفة 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>

تحويل سمة 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>

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

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

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

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

<person></person>

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

<person>I_AM_NULL</person>

العنصر <Options>/<InvalidCharsReplacement>

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

<InvalidCharsReplacement>_</InvalidCharsReplacement>

تحويل عنصر JSON هذا

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

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

<First_Name>John<First_Name>

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

في سيناريو التوسّط النموذجي، غالبًا ما يتم إقران سياسة JSON إلى XML في مسار طلب وارد بسياسة XML إلى JSON في مسار استجابة صادرة. ومن خلال الجمع بين السياسات بهذه الطريقة، يمكن عرض واجهة برمجة تطبيقات 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