سياسة JSONtoXML

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

المزايا

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

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

وبافتراض أن الغرض من ذلك هو تحويل طلب بتنسيق JSON إلى طلب بتنسيق XML، سيتم إرفاق السياسة بمسار الطلب (مثل الطلب / 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>

<Source> عنصر

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

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

إذا تعذَّر حلّ متغيّر المصدر أو إلى نوع آخر ليس رسالة، سيتم تطبيق السياسة إلى حدوث خطأ.

<Source>request</Source>

<OutputVariable> عنصر

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

يتم تحليل حمولة رسالة JSON وتحويلها إلى XML ونوع محتوى HTTP تم ضبط عنوان الرسالة بتنسيق 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 في مسار الطلب الوارد مع سياسة 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