سياسة XMLtoJSON

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

المزايا

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

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

<Source> عنصر

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

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

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

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

<Source>response</Source>

<OutputVariable> عنصر

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

يتم تحليل حمولة رسالة XML وتحويلها إلى تنسيق JSON، ونوع محتوى HTTP تم ضبط عنوان الرسالة بتنسيق XML على application/json.

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

<OutputVariable>response</OutputVariable>

<Options>

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

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

<Options>/<RecognizeNumber> عنصر

إذا كانت القيمة true، ستحتفظ حقول الأرقام في حمولة 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 true.

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

لاحظ أن الطالب 1 أصبح الآن في صفيف. والآن، بغض النظر عما إذا كان هناك ملف واحد أو أكثر طالب، يمكنك استردادها من مصفوفة 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.

<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 السياسة