מדיניות JSONtoXML

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

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

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

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

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

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

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

דוגמאות

לדיון מפורט, אפשר לעיין במאמר המרת נתונים בין XML ל-JSON באמצעות Apigee: מה שצריך לדעת.

המרת בקשה

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

ההגדרה הזו מקבלת הודעת בקשה בפורמט JSON כמקור, ואז יוצרת הודעה בפורמט XML שמאוכלסת במשתנה הפלט request. ‫Apigee משתמש באופן אוטומטי בתוכן של המשתנה הזה כהודעה לשלב העיבוד הבא.

הפניה לרכיב

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

<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>

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

מאפיין תיאור ברירת מחדל נוכחות
name

השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

 לא רלוונטי חובה
continueOnError

מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות.

הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף:

 FALSE אופציונלי
enabled

מגדירים את המדיניות למצב true כדי לאכוף אותה.

מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

 TRUE אופציונלי
async

המאפיין הזה הוצא משימוש.

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין name של המדיניות.
נוכחות אופציונלי
סוג String

רכיב <Source>

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

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

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

<Source>request</Source>
ברירת מחדל בקשה או תגובה, בהתאם למקום שבו המדיניות נוספת לזרימת ה-proxy ל-API
נוכחות אופציונלי
סוג הודעה

רכיב <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>
ברירת מחדל בקשה או תגובה, בהתאם למקום שבו המדיניות נוספת לזרימת ה-proxy ל-API
נוכחות האלמנט הזה הוא חובה כשהמשתנה שמוגדר באלמנט <Source> הוא מסוג מחרוזת.
סוג הודעה

<Options>/<OmitXmlDeclaration>

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

<?xml version="1.0" encoding="UTF-8"?>

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

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

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

‫<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>
ממיר את אובייקט ה-JSON הבא: 
{"person" : "I_AM_NULL"}

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

<person></person>

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

<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 Apigee 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.

Fault code HTTP status Cause Fix
steps.jsontoxml.ExecutionFailed 500 The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed.
steps.jsontoxml.InCompatibleTypes 500 This error occurs if the type of the variable defined in the <Source> element and the <OutputVariable> element are not the same. It is mandatory that the type of the variables contained within the <Source> element and the <OutputVariable> element matches. The valid types are message and string.
steps.jsontoxml.InvalidSourceType 500 This error occurs if the type of the variable used to define the <Source> element is invalid. The valid types of variable are message and string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 This error occurs if the variable specified in the <Source> element of the JSON to XML Policy is of type string and the <OutputVariable> element is not defined. The <OutputVariable> element is mandatory when the variable defined in the <Source> element is of type string.
steps.jsontoxml.SourceUnavailable 500 This error occurs if the message variable specified in the <Source> element of the JSON to XML policy is either:
  • Out of scope (not available in the specific flow where the policy is being executed) or
  • Can't be resolved (is not defined)

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.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. jsontoxml.JSON-to-XML-1.failed = true

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>

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