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

אין תמיכה במרחבי שמות ב-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> elements

‫<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, כך שהיא תופעל באופן מותנה. לדוגמה, אפשר לעיין במשתנים ותנאים של זרימת נתונים.

סכימות

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 ל-JSON: XML to JSON policy
• טרנספורמציית XSL: מדיניות XSL Transform