‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

מדיניות XMLtoJSON

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

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

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

המדיניות XMLtoJSON ממירה הודעות מפורמט XML (שפת סימון ניתנת להרחבה) לפורמט JSON (אובייקט ב-JavaScript). כך יש לכם כמה אפשרויות לשליטה באופן ההמרה של ההודעות.

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

<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` הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`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