מדיניות XMLtoJSON

מדיניות רגילה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

המדיניות XMLtoJSON ממירה הודעות מפורמט 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.

המרת תשובה

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

ההגדרה הזו – שהיא ההגדרה המינימלית שנדרשת להמרת XML ל-JSON – לוקחת הודעת תגובה בפורמט XML כמקור, ואז יוצרת הודעה בפורמט JSON שמאוכלסת ב-OutputVariable‏ response. ‫Apigee משתמש באופן אוטומטי בתוכן של המשתנה הזה כהודעה לשלב העיבוד הבא.

הפניה לרכיב

בהמשך מפורטים רכיבים ומאפיינים שאפשר להגדיר במדיניות הזו.

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

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

מאפיין	תיאור	ברירת מחדל	נוכחות
`name`	השם הפנימי של המדיניות. הערך של מאפיין `name` יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב `<DisplayName>` כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
`continueOnError`	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
`async`	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

משתמשים בו בנוסף למאפיין name כדי לתת למדיניות שם אחר בשפה טבעית, לסימון המדיניות בכלי לעריכת פרוקסי בממשק המשתמש לניהול.

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל

ברירת מחדל	לא רלוונטי אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין `name` של המדיניות.
נוכחות	אופציונלי
סוג	String

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין name של המדיניות.

נוכחות אופציונלי

סוג String

אלמנט <Source>

המשתנה שמציין את הודעת ה-XML שרוצים להמיר ל-JSON.

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

אם המדיניות <Source> לא מוגדרת, המערכת מתייחסת אליה כאילו היא message, שמוגדרת כ-request כשהמדיניות מצורפת לזרימת בקשות, או כ-response כשהמדיניות מצורפת לזרימת תגובות.

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

<Source>response</Source>

ברירת מחדל	הערך של רכיב `Source`
נוכחות	אופציונלי
סוג	הודעה

אלמנט <OutputVariable>

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

‫Apigee מנתח את המטען הייעודי (payload) של הודעת ה-XML שצוינה ב-Source, ממיר אותו ל-JSON, מאחסן את התוצאה במטען הייעודי (payload) של OutputVariable ומגדיר את כותרת Content-type של ה-HTTP של ההודעה OutputVariable ל-application/json.

אם לא מציינים את OutputVariable, המערכת משתמשת בערך של Source כברירת מחדל. לדוגמה, אם הערך של source הוא response, אז ערך ברירת המחדל של OutputVariable הוא response.

<OutputVariable>response</OutputVariable>

ברירת מחדל	ההודעה שצוינה ב`Source`
נוכחות	אופציונלי
סוג	הודעה

<Options>

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

המאפיין <Options> הוא חובה אם לא משתמשים במאפיין <Format>.

אלמנט <RecognizeNumber>

אם הערך הוא true, שדות המספרים במטען ה-XML שומרים על הפורמט המקורי שלהם.

<RecognizeNumber>true</RecognizeNumber>

דוגמה ל-XML:

<a>
  <b>100</b>
  <c>value</c>
</a>

אם RecognizeNumber הוא true, המדיניות ממירה אותו ל:

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

אם הערך של RecognizeNumber הוא false, המדיניות ממירה אותו ל:

{
  "a": {
    "b": "100",
    "c": "value"
  }
}

ברירת מחדל	FALSE
נוכחות	אופציונלי
סוג	בוליאני

<RecognizeBoolean> element

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

<RecognizeBoolean>true</RecognizeBoolean>

בדוגמת ה-XML הבאה:

<a>
  <b>true</b>
  <c>value</c>
</a>

אם RecognizeBoolean הוא true, המדיניות ממירה אותו ל:

{
    "a": {
        "b": true,
        "c": "value"
    }
}

אם RecognizeBoolean הוא false, המדיניות ממירה אותו ל:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

ברירת מחדל	FALSE
נוכחות	אופציונלי
סוג	בוליאני

אלמנט <RecognizeNull>

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

<RecognizeNull>true</RecognizeNull>

ב-XML הבא:

<a>
  <b></b>
  <c>value</c>
</a>

אם RecognizeNull הוא true, ואם אין אפשרות NullValue, קובץ ה-XML הזה יומר ל:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

אם הערך של RecognizeNull הוא false, קובץ ה-XML הזה יומר ל:

{
  "a": {
    "b": {},
    "c": "value"
  }
}

ברירת מחדל	FALSE
נוכחות	אופציונלי
סוג	בוליאני

אלמנט <NullValue>

מציין את הערך שאליו צריך להמיר ערכי null שזוהו בהודעת המקור. ערך ברירת המחדל הוא null. האפשרות הזו רלוונטית רק אם המדיניות RecognizeNull מוגדרת כ-True.

<NullValue>not-present</NullValue>

ב-XML הבא:

<a>
  <b></b>
  <c>value</c>
</a>

אם הערך של RecognizeNull הוא true, ולא צוין ערך ל-NullValue, קובץ ה-XML הזה יומר ל:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

אם הערך של RecognizeNull הוא true, והערך של NullValue הוא not-present, קובץ ה-XML הזה יומר ל:

{
  "a": {
    "b": "not-present",
    "c": "value"
  }
}

ברירת מחדל	`null`
נוכחות	אופציונלי
סוג	String

אפשרויות של מרחב שמות

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

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

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

אפשרויות טקסט

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

      <TextAlwaysAsProperty>true|false</TextAlwaysAsProperty>
      <TextNodeName>TEXT</TextNodeName>

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

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

לדוגמה, נניח שהגדרתם את המדיניות הבאה:

<XMLToJSON name='XMLToJSON-1'>
  <Options>
    <TextAlwaysAsProperty>???</TextAlwaysAsProperty>
    <TextNodeName>#text</TextNodeName>
  </Options>
</XMLToJSON>

עבור קלט ה-XML הנתון, המדיניות תיצור את הפלט הזה, בהתאם לשאלה אם TextAlwaysAsProperty הוא true או false:

קלט XML	פלט JSON
קלט XML	כשהערך בשדה `TextAlwaysAsProperty` הוא `false`	כשהערך בשדה `TextAlwaysAsProperty` הוא `true`
<a>value1</a>	{ "a": "value1" }	{ "a": { "#text": "value1" } }
<a>value1 <b>value2</b> </a>	{ "a": { "#text": "value1\n", "b": "value2" } }	{ "a": { "#text": "value1\n", "b": { "#text": "value2" } } }

ברירת מחדל	`<TextAlwaysAsProperty>`: false `<TextNodeName>`: (מחרוזת ריקה)
נוכחות	אופציונלי
סוג	‫`<TextAlwaysAsProperty>`: Boolean ‫`<TextNodeName>`: String

אפשרויות של מאפיינים

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

ברירת מחדל	אין.
נוכחות	אופציונלי
סוג	String

האלמנטים <OutputPrefix> ו-<OutputSuffix>

אפשר להשתמש באלמנטים האלה יחד כדי להוסיף קידומת או סיומת ל-JSON שנוצר.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

דוגמה ל-XML:

<a>value</a>

נניח שהגדרת המדיניות היא כזו:

<XMLToJSON name='XMLToJSON-4'>
  <Options>
    <OutputPrefix>{ "result": </OutputPrefix>
    <OutputSuffix>}</OutputSuffix>
  </Options>
</XMLToJSON>

נוצר מבנה ה-JSON הבא:

{
  "result": {
    "a": "value"
  }
}

אפשר להשמיט את OutputPrefix או את OutputSuffix, או את שניהם.

באמצעות הרכיבים האלה אפשר ליצור קובץ JSON לא תקין. לדוגמה, אם משתמשים בהגדרת המדיניות הזו:

<XMLToJSON name='XMLToJSON-4'>
  <Options>
    <OutputPrefix>PREFIX_</OutputPrefix>
  </Options>
</XMLToJSON>

המדיניות יוצרת את הפלט הבא, שהוא לא JSON תקין:

PREFIX_{
  "a" : "value"
}

אם בהגדרה לא מצוינים OutputPrefix או OutputSuffix, המדיניות יוצרת את מבנה ה-JSON הבא:

{
  "a": "value"
}

ברירת מחדל	דוגמאות מופיעות למעלה.
נוכחות	אופציונלי
סוג	String

אלמנט <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 וכן הלאה, תמשיכו לקבל את התגובה שלמעלה.

ברירת מחדל	‫0 (ללא הסרת רמה)
נוכחות	אופציונלי
סוג	מספר שלם

אלמנט <TreatAsArray>/<Path>

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

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

השימוש בפונקציה TreatAsArray יכול לשפר את המבנה של קודים עוקבים שמטפלים בפלט, כי הנתונים מהמערך מוחזרים באותו אופן בכל פעם. לדוגמה, הערכה של JSONPath של $.teachers.teacher.studentnames.name[0] תחזיר את הערך של השם הפרטי באופן עקבי, בין אם ה-XML המקורי הכיל רכיב name אחד או יותר.

בואו נחזור אחורה ונסתכל על התנהגות ברירת המחדל של XML ל-JSON, ואז נבדוק איך לשלוט בפלט באמצעות <TreatAsArray>/<Path>.

כשמסמך XML מכיל רכיב עם כמה מופעים (מה שיכול לקרות כשסכמת ה-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, שמוסבר בקטע הבא.

ברירת מחדל	לא רלוונטי
נוכחות	אופציונלי
סוג	String

מאפיינים

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

מאפיין תיאור נוכחות סוג

פתיחת האריזה של מפתח הצ

מאפיין	תיאור	נוכחות	סוג
פתיחת האריזה של מפתח הצ	ברירת מחדל: false הפעולה הזו מסירה את הרכיב מפלט ה-JSON. אפשר להשתמש באפשרות הזו כדי לייעל או לפשט את ה-JSON, מה שמקצר גם את ה-JSONPath שנדרש לאחזור ערכים. לדוגמה, במקום `$.teachers.teacher.studentnames.name[]`, אפשר לשטח את ה-JSON ולהשתמש ב-`$.teachers.studentnames[]`. דוגמה ל-JSON: { "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]}... בדוגמה הזו, אפשר לטעון שהרכיב `teacher` והרכיב studentnames `name` מיותרים. לכן אפשר להסיר אותם או לבטל את העטיפה שלהם. כך מגדירים את הרכיב `<Path>` כדי לעשות את זה: <TreatAsArray> <Path unwrap="true">teachers/teacher</Path> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> המאפיין `unwrap` מוגדר כ-true, והנתיבים לאלמנטים שצריך לבטל את העטיפה שלהם מסופקים. פלט ה-JSON ייראה כך: { "teachers" : [{ "name" : "teacherA", "studentnames" : ["student1","student2"] }]... שימו לב: מכיוון שהרכיב `<Path>` נמצא בתוך הרכיב `<TreatAsArray>`, שני הרכיבים בנתיב יטופלו כמערכים בפלט ה-JSON.	אופציונלי	בוליאני

ברירת מחדל: false

הפעולה הזו מסירה את הרכיב מפלט ה-JSON. אפשר להשתמש באפשרות הזו כדי לייעל או לפשט את ה-JSON, מה שמקצר גם את ה-JSONPath שנדרש לאחזור ערכים. לדוגמה, במקום $.teachers.teacher.studentnames.name[*], אפשר לשטח את ה-JSON ולהשתמש ב-$.teachers.studentnames[*].

דוגמה ל-JSON:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

בדוגמה הזו, אפשר לטעון שהרכיב teacher והרכיב studentnames name מיותרים. לכן אפשר להסיר אותם או לבטל את העטיפה שלהם. כך מגדירים את הרכיב <Path> כדי לעשות את זה:

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

המאפיין unwrap מוגדר כ-true, והנתיבים לאלמנטים שצריך לבטל את העטיפה שלהם מסופקים. פלט ה-JSON ייראה כך:

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

שימו לב: מכיוון שהרכיב <Path> נמצא בתוך הרכיב <TreatAsArray>, שני הרכיבים בנתיב יטופלו כמערכים בפלט ה-JSON.

אופציונלי

בוליאני

דוגמאות נוספות והסבר על התכונה זמינים במאמר הזה ב-Google Cloud Community.

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

ברירת מחדל	(ללא)
ערכים אפשריים	אחת מהאפשרויות הבאות: `xml.com`, ‏`yahoo`, ‏`google`, ‏`badgerFish`
נוכחות	אופציונלי, אבל חובה אם לא נעשה שימוש ב-`<Options>`.
סוג	String

סכימות

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מטרה
`steps.xmltojson.ExecutionFailed`	`ExecutionFailed`	השגיאה הזו מתרחשת כשמטען הייעודי (payload) של הקלט (XML) ריק, או כשקובץ ה-XML של הקלט לא תקין או פגום.
`steps.xmltojson.InCompatibleTypes`	`ExecutionFailed`	השגיאה הזו מתרחשת אם סוג המשתנה שמוגדר ברכיב `<Source>` וברכיב `<OutputVariable>` לא זהה. חובה שסוג המשתנים שמופיעים ברכיב `<Source>` וברכיב `<OutputVariable>` יהיה זהה.
`steps.xmltojson.InvalidSourceType`	`ExecutionFailed`	השגיאה הזו מתרחשת אם הסוג של המשתנה שמשמש להגדרת הרכיב `<Source>` לא תקין.הסוגים התקינים של המשתנה הם message ו-string.
`steps.xmltojson.OutputVariableIsNotAvailable`	`ExecutionFailed`	השגיאה הזו מתרחשת אם המשתנה שצוין ברכיב `<Source>` של מדיניות XML ל-JSON הוא מסוג מחרוזת, והרכיב `<OutputVariable>` לא מוגדר. הרכיב `<OutputVariable>` הוא חובה כשהמשתנה שמוגדר ברכיב `<Source>` הוא מסוג מחרוזת.
`steps.xmltojson.SourceUnavailable`	`ExecutionFailed`	השגיאה הזו מתרחשת אם המשתנה message שצוין ברכיב `<Source>` של מדיניות XML ל-JSON הוא אחד מהבאים: לא נכלל בהיקף (לא זמין בתהליך הספציפי שבו המדיניות מופעלת) או אי אפשר לפתור (לא מוגדר)

שגיאות פריסה

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

שם השגיאה	מטרה	תיקון
`EitherOptionOrFormat`	אם אחד מהרכיבים `<Options>` או `<Format>` לא מוצהר במדיניות XML ל-JSON, הפריסה של proxy ל-API תיכשל.
`UnknownFormat`	אם מוגדר פורמט לא ידוע לרכיב `<Format>` במדיניות XML ל-JSON, ה-Deployment (פריסה) של proxy ל-API נכשל. פורמטים מוגדרים מראש כוללים: `xml.com`,‏ `yahoo`,‏ `google` ו-`badgerFish`.

משתני תקלות

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

משתנים	כאשר:	דוגמה
`fault.name="fault_name"`	‫`fault_name` הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`fault.name = "SourceUnavailable"`
`xmltojson.policy_name.failed`	‫`policy_name` הוא השם שהמשתמש נתן למדיניות שגרמה לשגיאה.	`xmltojson.XMLtoJSON-1.failed = true`

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

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode בתגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

{
  "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: מדיניות JSONtoXML

מדיניות XMLtoJSON קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

דוגמאות

המרת תשובה

הפניה לרכיב

מאפיינים של התג <XMLtoJSON>

אלמנט <DisplayName>

אלמנט <Source>

אלמנט <OutputVariable>

<Options>

אלמנט <RecognizeNumber>

<RecognizeBoolean> element

אלמנט <RecognizeNull>

אלמנט <NullValue>

אפשרויות של מרחב שמות

אפשרויות טקסט

אפשרויות של מאפיינים

האלמנטים <OutputPrefix> ו-<OutputSuffix>

אלמנט <StripLevels>

אלמנט <TreatAsArray>/<Path>

מאפיינים

<Format>

xml.com

yahoo

google

badgerFish

סכימות

הפניה לשגיאה

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

שגיאות פריסה

משתני תקלות

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

דוגמה לכלל שגיאה

נושאים קשורים

מדיניות XMLtoJSON