מדיניות JSONtoXML

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

מה

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

המדיניות הזו שימושית במיוחד אם רוצים לשנות הודעות באמצעות XSL. אחרי שממירים מטען ייעודי (payload) בפורמט JSON ל-XML, משתמשים במדיניות XSL Transform עם גיליון סגנונות מותאם אישית כדי לבצע את ההמרה שנדרשת.

בהנחה שהכוונה היא להמיר בקשה בפורמט JSON לבקשה בפורמט XML, המדיניות תצורף ל-Flow של בקשה (לדוגמה, Request / ProxyEndpoint / PostFlow).

דוגמאות

דיון מפורט על המרה בין JSON ל-XML מופיע במאמר בעיה בהמרת מערך JSON למערך XML באובייקט התגובה.

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

הפניה לרכיב

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

<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1">
    <DisplayName>JSON to XML 1</DisplayName>
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
    <Options>
        <OmitXmlDeclaration>false</OmitXmlDeclaration>
        <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
        <NamespaceSeparator>:</NamespaceSeparator>
        <AttributeBlockName>#attrs</AttributeBlockName>
        <AttributePrefix>@</AttributePrefix>
        <ObjectRootElementName>Root</ObjectRootElementName>
        <ArrayRootElementName>Array</ArrayRootElementName>
        <ArrayItemElementName>Item</ArrayItemElementName>
        <Indent>false</Indent>
        <TextNodeName>#text</TextNodeName>
        <NullValue>I_AM_NULL</NullValue>
        <InvalidCharsReplacement>_</InvalidCharsReplacement>
    </Options>
</JSONToXML>

מאפיינים של <JSONToXML>

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

רכיב <Source>

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

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

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

<Source>request</Source>

רכיב <OutputVariable>

מאחסן את הפלט של ההמרה מפורמט JSON לפורמט XML. בדרך כלל זהו אותו ערך כמו המקור, כלומר בדרך כלל בקשת JSON מומרת לבקשת XML.

המטען הייעודי (payload) של הודעת ה-JSON מנותח ומומר ל-XML, וכותרת ה-HTTP Content-type של ההודעה בפורמט XML מוגדרת ל-text/xml;charset=UTF-8.

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

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

מציין להשמיט את מרחב השמות של ה-XML מהפלט. ערך ברירת המחדל הוא false, כלומר מרחב השמות ייכלל בפלט.

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

‫<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

אין תמיכה במרחבי שמות ב-JSON, אבל לעיתים קרובות נדרשים מרחבי שמות במסמכי XML. ‫NamespaceBlockName מאפשרת להגדיר נכס JSON שמשמש כמקור להגדרת מרחב שמות ב-XML שנוצר על ידי המדיניות. (כלומר, קובץ ה-JSON של המקור צריך לספק מאפיין שאפשר למפות למרחב שמות שהאפליקציה מצפה לו, ושצורכת את קובץ ה-XML שנוצר).

לדוגמה, ההגדרות הבאות:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

מציין שקיים בקובץ ה-JSON של המקור מאפיין בשם #namespaces שמכיל לפחות מרחב שמות אחד שמוגדר כברירת מחדל. לדוגמה:

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

תומר ל:

<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers">
  <person>John Smith</person>
  <exp:person>Pedro Cabral</exp:person>
</population>

<Options>/<ObjectRootElementName>

‫<ObjectRootElementName> מציין את שם רכיב הבסיס כשממירים מ-JSON, שאין לו רכיב בסיס עם שם, ל-XML.

לדוגמה, אם ה-JSON נראה כך:

{
  "abc": "123",
  "efg": "234"
}

מגדירים את <ObjectRootElementName> כך:

<ObjectRootElementName>Root</ObjectRootElementName>

קובץ ה-XML שמתקבל נראה כך:

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

‫<Options>/<AttributeBlockName>
‫<Options>/<AttributePrefix>

‫<AttributeBlockName> מאפשר לציין מתי רכיבי JSON מומרים למאפייני XML (במקום לרכיבי XML).

לדוגמה, ההגדרה הבאה ממירה מאפיינים בתוך אובייקט בשם #attrs למאפייני XML:

<AttributeBlockName>#attrs</AttributeBlockName>

אובייקט ה-JSON הבא:

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },
        "occupation" : "explorer",
    }
}

מומר למבנה ה-XML הבא:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

‫<AttributePrefix> ממיר את הנכס שמתחיל בקידומת שצוינה לתכונות XML. לדוגמה, אם קידומת המאפיין מוגדרת כ-@:

<AttributePrefix>@</AttributePrefix>

ממיר את אובייקט ה-JSON הבא:

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

למבנה ה-XML הבא:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

‫<Options>/<ArrayRootElementName>
‫<Options>/<ArrayItemElementName> element

הפונקציה ממירה מערך JSON לרשימה של רכיבי XML עם שמות של רכיבי אב ורכיבי צאצא שצוינו.

לדוגמה, ההגדרות הבאות:

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

ממיר את מערך ה-JSON הבא:

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

למבנה ה-XML הבא:

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

<Options>/<Indent>

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

לדוגמה, ההגדרה הבאה קובעת שהמדיניות תבצע הזחה של הפלט:

<Indent>true</Indent>

אם קלט ה-JSON הוא מהצורה:

{"n": [1, 2, 3] }

הפלט בלי הזחה הוא:

<Array><n>1</n><n>2</n><n>3</n></Array>

אם ההזחה מופעלת, הפלט הוא:

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

אלמנט <Options>/<TextNodeName>

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

<TextNodeName>age</TextNodeName>

הקוד הבא ממיר את ה-JSON הזה:

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

למבנה ה-XML הזה:

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

אם לא מציינים את TextNodeName, ה-XML נוצר באמצעות הגדרת ברירת המחדל של צומת טקסט:

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

אלמנט <Options>/<NullValue>

מציין ערך null. ערך ברירת המחדל הוא NULL.

לדוגמה, ההגדרה הבאה:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

לרכיב ה-XML הבא:

<person></person>

אם לא מציינים ערך (או מציינים ערך שאינו I_AM_NULL) עבור הערך Null, אותה מטען ייעודי (payload) מומר ל:

<person>I_AM_NULL</person>

אלמנט <Options>/<InvalidCharsReplacement>

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

<InvalidCharsReplacement>_</InvalidCharsReplacement>

ממיר את אובייקט ה-JSON הזה

{
    "First%%%Name": "John"
}

למבנה ה-XML הזה:

<First_Name>John<First_Name>

הערות שימוש

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

לעתים קרובות כדאי להחיל את מדיניות ברירת המחדל (ריקה) של JSON ל-XML ולהוסיף בהדרגה רכיבי הגדרה לפי הצורך.

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

סכימות

הפניה לשגיאה

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

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

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

שגיאות פריסה

ללא.

משתני כשל

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

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

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

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

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

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

• ‫XML to JSON: XML to JSON policy
• טרנספורמציית XSL: מדיניות XSL Transform