מדיניות JSONtoXML

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מה

המדיניות הזו ממירה הודעות בפורמט JavaScript Object Notation (JSON) לפורמט שניתן להרחבה שפת סימון (XML), שמעניקה לך כמה אפשרויות לשליטה באופן ההמרה של הודעות.

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

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

דוגמאות

דיון מפורט על המרה בין JSON ל-XML זמין בכתובת http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.

<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> מאפיינים

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

<DisplayName> רכיב

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

<DisplayName>Policy Display Name</DisplayName>

<Source> רכיב

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

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

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

<Source>request</Source>

<OutputVariable> רכיב

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

המטען הייעודי (Payload) של הודעת ה-JSON מנותח ומומר ל-XML, ואת סוג התוכן ב-HTTP הכותרת של ההודעה בפורמט 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>

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

{
   "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> רכיב

הפונקציה ממירה מערך 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 בתהליך הבקשה הנכנסת מותאמת למדיניות XMLtoJSON בזרימת התגובה היוצאת. על ידי שילוב של כללי מדיניות בדרך הזו, אפשר לחשוף 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 ל-JSON מדיניות
• טרנספורמציה של XSL: מדיניות טרנספורמציה של XSL