Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

האפשרות 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 policy

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

דוגמאות

המרת תשובה

הפניה לרכיב

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

אלמנט <DisplayName>

רכיב <Source>

רכיב <OutputVariable>

<Options>

רכיב <RecognizeNumber>

<RecognizeBoolean> element

רכיב <RecognizeNull>

אלמנט <NullValue>

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

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

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

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

אלמנט <StripLevels>

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

מאפיינים

<Format>

xml.com

yahoo

google

badgerFish

סכימות

הפניה לשגיאה

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

שגיאות בהטמעה

משתני תקלות

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

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

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

מדיניות XMLtoJSON