سياسة XMLtoJSON

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

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

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

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

لمحة

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

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

نماذج

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

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

مرجع العنصر

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

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</DisplayName>
    <Source>response</Source>
    <OutputVariable>response</OutputVariable>
    <Options>
        <RecognizeNumber>true</RecognizeNumber>
        <RecognizeBoolean>true</RecognizeBoolean>
        <RecognizeNull>true</RecognizeNull>
        <NullValue>NULL</NullValue>
        <NamespaceBlockName>#namespaces</NamespaceBlockName>
        <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
        <NamespaceSeparator>***</NamespaceSeparator>
        <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
        <TextNodeName>TEXT</TextNodeName>
        <AttributeBlockName>FOO_BLOCK</AttributeBlockName>
        <AttributePrefix>BAR_</AttributePrefix>
        <OutputPrefix>PREFIX_</OutputPrefix>
        <OutputSuffix>_SUFFIX</OutputSuffix>
        <StripLevels>2</StripLevels>
        <TreatAsArray>
            <Path unwrap="true">teachers/teacher/studentnames/name</Path>
        </TreatAsArray>
    </Options>
    <!-- Use Options or Format, not both -->
    <Format>yahoo</Format>
</XMLToJSON>

سمات <XMLtoJSON>

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">

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

&lt;DisplayName&gt; عنصر

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

<DisplayName>Policy Display Name</DisplayName>

العنصر <Source>

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

يجب ضبط عنوان HTTP Content-type للرسالة المصدر على application/xml، وإلا لن يتم فرض السياسة.

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

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

<Source>response</Source>

عنصر <OutputVariable>

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

يتم تحليل حمولة رسالة XML وتحويلها إلى JSON، ويتم ضبط عنوان HTTP Content-type الخاص بالرسالة المنسَّقة بتنسيق XML على application/json.

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

<OutputVariable>response</OutputVariable>

<خيارات>

تمنحك الخيارات إمكانية التحكّم في عملية التحويل من XML إلى JSON. استخدِم المجموعة <Options> التي تتيح لك إضافة إعدادات إحالات ناجحة معيّنة، أو العنصر <Format> الذي يتيح لك الإشارة إلى نموذج يتضمّن خيارات محدّدة مسبقًا. لا يمكنك استخدام كل من <Options> و<Format>.

السمة <Options> مطلوبة في حال عدم استخدام السمة <Format>.

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

إذا كانت القيمة صحيحة، ستحتفظ حقول الأرقام في حمولة XML بتنسيقها الأصلي.

<RecognizeNumber>true</RecognizeNumber>

إليك مثالاً على XML:

<a>
  <b>100</b>
  <c>value</c>
</a>

إذا كانت القيمة true، يتم التحويل إلى:

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

إذا كانت القيمة false، يتم التحويل إلى:

{
    "a": {
        "b": "100",
        "c": "value"
    }
}

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

تتيح هذه السمة للإحالة الناجحة الاحتفاظ بالقيم المنطقية "صحيح" أو "خطأ" بدلاً من تحويل القيم إلى سلاسل.

<RecognizeBoolean>true</RecognizeBoolean>

في مثال XML التالي:

<a>
  <b>true</b>
  <c>value</c>
</a>

إذا كانت القيمة true، يتم التحويل إلى:

{
    "a": {
        "b": true,
        "c": "value"
    }
}

إذا كانت القيمة false، يتم التحويل إلى:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

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

تتيح لك تحويل القيم الفارغة إلى قيم فارغة.

<RecognizeNull>true</RecognizeNull>

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

<a>
  <b></b>
  <c>value</c>
</a>

إذا كانت القيمة true، يتم التحويل إلى:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

إذا كانت القيمة false، يتم التحويل إلى:

{
  "a": {
    "b": {},
    "c": "value"
  }
}

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

تشير إلى القيمة التي يجب تحويل قيم Null المعروفة في الرسالة المصدر إليها. القيمة التلقائية هي null. لن يكون لهذا الخيار أي تأثير إلا إذا كانت قيمة RecognizeNull هي "صحيح".

<NullValue>not-present</NullValue>

عناصر <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

استخدِم هذه العناصر معًا.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
<NamespaceSeparator>***</NamespaceSeparator>

إليك مثالاً على XML:

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">
  <ns1:b>value</ns1:b>
</a>

في حال عدم تحديد NamespaceSeparator، يتم إنشاء بنية JSON التالية:

{
    "a": {
        "b": "value"
    }
}

إذا تم تحديد العناصر NamespaceBlockName وDefaultNamespaceNodeName وNamespaceSeparator على أنّها #namespaces و& و*** على التوالي، سيتم إنشاء بنية JSON التالية:

{
    "a": {
        "#namespaces": {
            "&": "http://ns.com",
            "ns1": "http://ns1.com"
        },
        "ns1***b": "value"
    }
}

عناصر <Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>

استخدِم هذه العناصر معًا.

إذا تم ضبطها على true، سيتم تحويل محتوى عنصر XML إلى سمة سلسلة.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

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

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

إذا تم ضبط TextAlwaysAsProperty على true وتم تحديد TextNodeName على النحو TEXT، سيتم إنشاء بنية JSON التالية:

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

إذا تم ضبط TextAlwaysAsProperty على false وتم تحديد TextNodeName على النحو TEXT، سيتم إنشاء بنية JSON التالية:

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}

عناصر <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

استخدِم هذه العناصر معًا.

تتيح لك تجميع القيم في حزمة JSON وإضافة بادئات إلى أسماء السمات.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName>
<AttributePrefix>BAR_</AttributePrefix>

إليك مثالاً على XML:

<a attrib1="value1" attrib2="value2"/>

إذا تم تحديد كلتا السمتين (AttributeBlockName وAttributePrefix) كما هو موضّح في مثال XML إلى JSON، سيتم إنشاء بنية JSON التالية:

{
  "a": {
    "FOO_BLOCK": {
      "BAR_attrib1": "value1",
      "BAR_attrib2": "value2"
    }
  }
}

إذا تم تحديد AttributeBlockName فقط، سيتم إنشاء بنية JSON التالية:

{
    "a": {
        "FOO_BLOCK": {
            "attrib1": "value1",
            "attrib2": "value2"
        }
    }
}

إذا تم تحديد AttributePrefix فقط، سيتم إنشاء بنية JSON التالية:

{
    "a": {
        "BAR_attrib1": "value1",
        "BAR_attrib2": "value2"
    }
}

في حال عدم تحديد أي منهما، يتم إنشاء بنية JSON التالية:

{
    "a": {
        "attrib1": "value1",
        "attrib2": "value2"
    }
}

عناصر <Options>/<OutputPrefix>
<Options>/<OutputSuffix>

استخدِم هذه العناصر معًا.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

إليك مثالاً على XML:

<a>value</a>

إذا تم تحديد كلتا السمتين (OutputPrefix وOutputSuffix) كما هو موضّح في مثال XML إلى JSON، سيتم إنشاء بنية JSON التالية:

PREFIX_{
    "a": "value"
}_SUFFIX

في حال تحديد OutputPrefix فقط، يتم إنشاء بنية JSON التالية:

PREFIX_{
  "a" : "value"
}

في حال تحديد OutputSuffix فقط، يتم إنشاء بنية JSON التالية:

{
  "a" : "value"
}_SUFFIX

إذا لم يتم تحديد أي من السمتَين OutputPrefix أو OutputSuffix، سيتم إنشاء بنية JSON التالية:

{
    "a": "value"
}

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

<Options>
    <StripLevels>4</StripLevels>
</Options>

في بعض الأحيان، تحتوي حمولات XML، مثل SOAP، على العديد من مستويات العناصر الرئيسية التي لا تريد تضمينها في JSON المحوَّل. في ما يلي مثال على استجابة SOAP تتضمّن عدة مستويات:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
          <GetCityWeatherByZIPResult>
              <State>CO</State>
              <City>Denver</City>
              <Description>Sunny</Description>
              <Temperature>62</Temperature>
          </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
  </soap:Body>
</soap:Envelope>

هناك 4 مستويات قبل الوصول إلى مستوى الولاية والمدينة والوصف ودرجة الحرارة. بدون استخدام <StripLevels>، ستظهر استجابة JSON المحوَّلة على النحو التالي:

{
   "Envelope" : {
      "Body" : {
         "GetCityWeatherByZIPResponse" : {
            "GetCityWeatherByZIPResult" : {
               "State" : "CO",
               "City" : "Denver",
               "Description" : "Sunny",
               "Temperature" : "62"
            }
         }
      }
   }
}

إذا أردت إزالة المستويات الأربعة الأولى في استجابة JSON، عليك ضبط <StripLevels>4</StripLevels>، ما سيؤدي إلى ظهور JSON التالي:

{
  "State" : "CO",
  "City" : "Denver",
  "Description" : "Sunny",
  "Temperature" : "62"
}

يمكنك إزالة المستويات حتى العنصر الأول الذي يحتوي على عناصر ثانوية متعددة. ماذا يعني ذلك؟ لنلقِ نظرة على مثال أكثر تعقيدًا بتنسيق JSON:

{
   "Envelope" : {
      "Body" : {
         "GetCityForecastByZIPResponse" : {
            "GetCityForecastByZIPResult" : {
               "ResponseText" : "City Found",
               "ForecastResult" : {
                  "Forecast" : [
                     {
                        "ProbabilityOfPrecipiation" : {
                           "Nighttime" : "00",
                           "Daytime" : 10
                        }  ...

المستوى 3 في هذا المثال هو GetCityForecastByZIPResponse، الذي يتضمّن عنصرًا فرعيًا واحدًا فقط. لذلك، إذا كنت ستستخدم <StripLevels>3</StripLevels> (إزالة المستويات الثلاثة الأولى)، سيظهر ملف JSON على النحو التالي:

{
   "GetCityForecastByZIPResult" : {
      "ResponseText" : "City Found",
      "ForecastResult" : {
         "Forecast" : [
            {
               "ProbabilityOfPrecipiation" : {
                  "Nighttime" : "00",
                  "Daytime" : 10
               }  ...

لاحظ أنّ GetCityForecastByZIPResult يتضمّن عناصر فرعية متعددة. بما أنّه العنصر الأول الذي يحتوي على عناصر فرعية متعددة، يمكنك إزالة هذا المستوى الأخير باستخدام <StripLevels>4</StripLevels>، ما سيؤدي إلى ظهور JSON التالي:

{
   "ResponseText" : "City Found",
   "ForecastResult" : {
      "Forecast" : [
         {
            "ProbabilityOfPrecipiation" : {
               "Nighttime" : "00",
               "Daytime" : 10
            }  ...

بما أنّ المستوى 4 هو المستوى الأول الذي يحتوي على عدة عناصر فرعية، لا يمكنك إزالة أي مستويات أقل من هذا المستوى. إذا ضبطت مستوى الشريط على 5 أو 6 أو 7 وما إلى ذلك، سيستمر ظهور الردّ أعلاه.

العنصر <Options>/<TreatAsArray>/<Path>

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

يتيح لك هذا المزيج من العناصر التأكّد من وضع القيم من مستند XML في مصفوفة JSON. يكون ذلك مفيدًا، مثلاً، عندما يمكن أن يختلف عدد العناصر الفرعية (من عنصر واحد إلى عدة عناصر)، وتريد التأكّد من أنّ القيم تكون دائمًا في مصفوفة. يساعد ذلك في الحفاظ على ثبات الرمز البرمجي، لأنّه يمكنك الحصول على البيانات من المصفوفة بالطريقة نفسها في كل مرة. على سبيل المثال، تعرض الدالة $.teachers.teacher.studentnames[0] قيمة اسم الطالب الأولى في المصفوفة بغض النظر عن عدد القيم في المصفوفة.

لنرجع خطوة إلى الوراء ونلقي نظرة على السلوك التلقائي لتحويل XML إلى JSON، ثم نستكشف كيفية التحكّم في الناتج باستخدام <TreatAsArray>/<Path>.

عندما يحتوي مستند XML على عنصر يتضمّن قيمًا ثانوية متعددة (عادةً استنادًا إلى مخطط يكون فيه العنصر maxOccurs='unbounded')، تضع سياسة XML إلى JSON هذه القيم تلقائيًا في مصفوفة. على سبيل المثال، كتلة XML التالية

<teacher>
    <name>teacherA</name>
    <studentnames>
        <name>student1</name>
        <name>student2</name>
    </studentnames>
</teacher>

...يتم تحويلها تلقائيًا إلى JSON التالي بدون أي إعدادات خاصة بالسياسة:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}
           }
      }
}

لاحظ أنّه تم وضع اسمَي الطالبَين في مصفوفة.

ومع ذلك، إذا ظهر طالب واحد فقط في مستند XML، ستتعامل سياسة XML إلى JSON تلقائيًا مع القيمة كسلسلة واحدة، وليس كمجموعة من السلاسل، كما هو موضّح في المثال التالي:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : "student1"
              }
          }
      }
}

في الأمثلة السابقة، تم تحويل البيانات المشابهة بشكل مختلف، مرة كمصفوفة ومرة أخرى كسلسلة واحدة. هنا يأتي دور العنصر <TreatAsArray>/<Path> في السماح لك بالتحكّم في الناتج. يمكنك، على سبيل المثال، التأكّد من أنّ أسماء الطلاب يتم وضعها دائمًا في مصفوفة حتى لو كانت هناك قيمة واحدة فقط. يمكنك ضبط ذلك من خلال تحديد مسار العنصر الذي تريد وضع قيمه في مصفوفة، على النحو التالي:

<Options>
    <TreatAsArray>
        <Path>teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

ستكتب الإعدادات أعلاه ملف JSON على النحو التالي:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : ["student1"]
              }
            ]
          }
      }
}

لاحظ أنّ student1 أصبح الآن في مصفوفة. الآن، بغض النظر عمّا إذا كان هناك طالب واحد أو عدة طلاب، يمكنك استردادهم من مصفوفة JSON في الرمز البرمجي باستخدام JSONPath التالي: $.teachers.teacher.studentnames.name[0]

يحتوي العنصر <Path> أيضًا على السمة unwrap، التي سيتم شرحها في القسم التالي.

السمات

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

للاطّلاع على المزيد من الأمثلة وشرح الميزة، راجِع مقالة "منتدى Apigee" هذه: Community tutorial: The TreatAsArray option in the XML to JSON policy.

<Format>

يمنحك التنسيق التحكّم في عملية التحويل من XML إلى JSON. أدخِل اسم نموذج محدّد مسبقًا يحتوي على مجموعة معيّنة من عناصر الخيارات الموضّحة في هذا الموضوع. تشمل التنسيقات المحدّدة مسبقًا ما يلي: xml.com وyahoo وgoogle وbadgerFish.

استخدِم العنصر <Format> أو المجموعة <Options>. لا يمكنك استخدام كل من <Format> و<Options>.

في ما يلي تعريفات التنسيق لكل نموذج محدّد مسبقًا.

xml.com

<RecognizeNull>true</RecognizeNull>
<TextNodeName>#text</TextNodeName>
<AttributePrefix>@</AttributePrefix>

yahoo

<RecognizeNumber>true</RecognizeNumber>
<TextNodeName>content</TextNodeName>

Google

<TextNodeName>$t</TextNodeName>
<NamespaceSeparator>$</NamespaceSeparator>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>

badgerFish

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

بنية العنصر:

<Format>yahoo</Format>

المخططات

مرجع الخطأ

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

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

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

أخطاء النشر

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

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

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

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

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

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

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

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

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