سياسة XMLtoJSON

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

الموضوع

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

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

لمحة عامة

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

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

عيّنات

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

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

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

العنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

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

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

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

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

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

<Source>response</Source>

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

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

يتم تحليل حمولة رسالة XML وتحويلها إلى JSON، ويتم ضبط العنوان "نوع محتوى HTTP" للرسالة بتنسيق 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. ولا يسري هذا الخيار إلا إذا كانت قيمة 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>/<Text AlwaysAsProperty>
عناصر <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>/<setupPrefix>
عناصر <Options>/<الإخراجSuffix>

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

<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"]
              }
            ]
          }
      }
}

لاحظ أن students1 الآن في صفيف. وبغض النظر عمّا إذا كان هناك طالب واحد أو عدة طالب، يمكنك استردادهم من مصفوفة 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 هذه: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html.

<التنسيق>

يتيح لك التنسيق التحكّم في عملية التحويل من 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