מדיניות XMLtoJSON

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

מה

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

בהנחה שהכוונה היא להמיר תגובה בפורמט 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 בהודעת המקור צריכה להיות מוגדרת ל-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> elements

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

<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 רמות לפני שמגיעים לרמה של מדינה, עיר, תיאור וטמפרטורה. בלי להשתמש ב-<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 to 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 (מדריך לקהילה: האפשרות TreatAsArray במדיניות XML ל-JSON).

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

סכימות

הפניה לשגיאה

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

שגיאות זמן ריצה

השגיאות האלה עשויות להתרחש כשהמדיניות מופעלת.

שגיאות פריסה

השגיאות האלו עשויות להתרחש כאשר פורסים שרת proxy שמכיל את המדיניות הזו.

משתני כשל

המשתנים האלה מוגדרים כשמתרחשת שגיאה בסביבת זמן הריצה. מידע נוסף זמין במאמר מה צריך לדעת? על שגיאות שקשורות למדיניות.

דוגמה לתגובת שגיאה

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