سياسة JSONtoXML

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

الموضوع

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

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

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

عيّنات

للحصول على مناقشة تفصيلية حول التحويل بين JSON وXML، يُرجى الاطّلاع على http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.

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

يوضِّح الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

العنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

عنصر <المصدر>

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

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

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

<Source>request</Source>

عنصر <الإخراجVariable>

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

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

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

<OutputVariable>request</OutputVariable>

<الخيارات>/<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>

<خيارات>/<مسافة بادئة>

يحدِّد هذا الإعداد إضافة مسافة بادئة إلى إخراج 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 في مسار الطلبات الواردة مع سياسة 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