מדיניות XMLtoJSON

אתם צופים במסמכי התיעוד של Apigee Edge.
אפשר לעבור אל מסמכי התיעוד של Apigee X. מידע

מה

המדיניות הזו ממירה הודעות מפורמט XML (שפת תגי עיצוב ניתנת להרחבה) לפורמט JSON (JavaScript Object Notation). כך יש לכם כמה אפשרויות לשליטה באופן ההמרה של ההודעות.

אם הכוונה היא להמיר תגובה בפורמט XML לתגובה בפורמט JSON, המדיניות תצורף ל-Flow של תגובה (לדוגמה, Response / ProxyEndpoint / PostFlow).

מידע כללי

בתרחיש טיפוסי של גישור, מדיניות JSON ל-XML בזרימת הבקשות הנכנסות משולבת לעיתים קרובות עם מדיניות XML ל-JSON בזרימת התגובות היוצאות. באמצעות שילוב של כללי מדיניות בדרך הזו, אפשר לחשוף API בפורמט JSON לשירותי קצה עורפי שתומכים באופן טבעי רק ב-XML.

בתרחישים שבהם ממשקי API נצרכים על ידי אפליקציות לקוח מגוונות שעשויות לדרוש 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 כדי להוסיף תווית למדיניות עורך proxy של ממשק משתמש לניהול עם שם אחר בשפה טבעית.

<DisplayName>Policy Display Name</DisplayName>

אלמנט <Source>

המשתנה, הבקשה או התגובה שמכילים את הודעת ה-XML שרוצים להמיר ל-JSON.

כותרת ה-HTTP Content-type של הודעת המקור צריכה להיות מוגדרת ל-application/xml, אחרת המדיניות לא נאכפת.

אם <Source> לא מוגדר, הוא נחשב כהודעה (שמפוענחת כבקשה כשהמדיניות מצורפת לזרימת בקשות, או כתגובה כשהמדיניות מצורפת לזרימת תגובות).

אם אי אפשר לפתור את משתנה המקור, או שהוא נפתר כסוג שאינו הודעה, המדיניות מציגה שגיאה.

<Source>response</Source>

אלמנט <OutputVariable>

מאחסן את הפלט של ההמרה מפורמט XML לפורמט JSON. בדרך כלל זהו אותו ערך כמו המקור, כלומר, בדרך כלל תגובת XML מומרת לתגובת JSON.

המטען הייעודי (payload) של הודעת ה-XML מנותח ומומר ל-JSON, וכותרת ה-HTTP Content-type של ההודעה בפורמט 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>

ההגדרה מאפשרת להמרה לשמור על ערכים בוליאניים של true/false במקום להפוך את הערכים למחרוזות.

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

מאפשרת להמיר ערכים ריקים לערכי null.

<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 מוגדרת כ-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> elements

משתמשים ברכיבים האלה יחד.

מאפשר לקבץ ערכים לבלוק 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>

לפעמים, למטענים ייעודיים (payloads) של 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"
            }
         }
      }
   }
}

אם רוצים להסיר את 4 הרמות הראשונות בתגובת ה-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. האפשרות הזו שימושית, למשל, כשמספר רכיבי הצאצא יכול להשתנות (מ-1 לכמה), ואתם רוצים לוודא שהערכים תמיד יהיו במערך. הפעולה הזו עוזרת לשמור על יציבות הקוד, כי אפשר לקבל נתונים מהמערך באותה דרך בכל פעם. לדוגמה: $.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>

‫...gets converted into the following JSON automatically with no special policy configuration:

{
  "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. מזינים את השם של תבנית מוגדרת מראש שמכילה שילוב ספציפי של רכיבי Options שמתוארים בנושא הזה. הפורמטים המוגדרים מראש כוללים: 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>

סכימות

הפניה לשגיאה

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

These errors can occur when you deploy a proxy containing this policy.

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": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Example fault rule

<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