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

צריך להגדיר את הכותרת מסוג Content-type של 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>

<אפשרויות>

האפשרויות מאפשרות לך לשלוט בהמרה מ-XML ל-JSON. מומלץ להשתמש בקבוצה <Options>, שמאפשרת להוסיף הגדרות ספציפיות של המרות, או ברכיב <Format> שמאפשר להפנות לתבנית של אפשרויות שהוגדרו מראש. לא ניתן להשתמש גם ב-<Options> וגם ב-<Format>.

אם לא משתמשים ב-<Format>, חובה לציין את הפרמטר <Options>.

רכיב <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>

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

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

<פורמט>

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

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

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

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת 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