מדיניות XMLtoJSON

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

מה

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

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

מידע כללי

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

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

השתמשו באלמנטים האלה יחד.

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

סכימות

התייחסות לשגיאות

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 מדיניות