מדיניות JSONtoXML

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

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

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

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

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

הערה: כותרת ה-HTTP Content-type של הודעת המקור חייבת להיות מוגדרת כ-application/json, אחרת המדיניות לא נאכפת, כלומר המערכת מדלגת עליה במהלך העיבוד.

בהנחה שהכוונה היא להמיר בקשה בפורמט 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` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
`async`	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל

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

לא רלוונטי

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

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

סכימות

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מטרה
`steps.jsontoxml.ExecutionFailed`	`500`	המטען הייעודי (payload) של הקלט (JSON) ריק, או שהקלט (JSON) שהועבר למדיניות JSON to XML לא תקין או פגום.
`steps.jsontoxml.InCompatibleTypes`	`500`	השגיאה הזו מתרחשת אם סוג המשתנה שמוגדר ברכיב `<Source>` וברכיב `<OutputVariable>` לא זהה. חובה שסוג המשתנים שמופיעים ברכיב `<Source>` וברכיב `<OutputVariable>` יהיה זהה. הסוגים התקינים הם `message` ו-`string`.
`steps.jsontoxml.InvalidSourceType`	`500`	השגיאה הזו מתרחשת אם הסוג של המשתנה שמשמש להגדרת הרכיב `<Source>` לא תקין. סוגי המשתנים התקינים הם `message` ו-`string`.
`steps.jsontoxml.OutputVariableIsNotAvailable`	`500`	השגיאה הזו מתרחשת אם המשתנה שצוין ברכיב `<Source>` של מדיניות JSON ל-XML הוא מסוג מחרוזת, והרכיב `<OutputVariable>` לא מוגדר. הרכיב `<OutputVariable>` הוא חובה כשהמשתנה שמוגדר ברכיב `<Source>` הוא מסוג מחרוזת.
`steps.jsontoxml.SourceUnavailable`	`500`	השגיאה הזו מתרחשת אם המשתנה message שצוין ברכיב `<Source>` של מדיניות JSON ל-XML הוא אחד מהבאים: לא נכלל בהיקף (לא זמין בתהליך הספציפי שבו המדיניות מופעלת) או אי אפשר לפתור (לא מוגדר)

שגיאות פריסה

אין.

משתני תקלות

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

משתנים	כאשר:	דוגמה
`fault.name="fault_name"`	‫`fault_name` הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`fault.name Matches "SourceUnavailable"`
`jsontoxml.policy_name.failed`	‫`policy_name` הוא השם שהמשתמש נתן למדיניות שגרמה לשגיאה.	`jsontoxml.JSON-to-XML-1.failed = true`

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

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode בתגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

{
  "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 ל-JSON: מדיניות XMLtoJSON
טרנספורמציית XSL: XSLTransform policy

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

דוגמאות

המרת בקשה

הפניה לרכיב

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

אלמנט <DisplayName>

אלמנט <Source>

אלמנט <OutputVariable>

<Options>/<OmitXmlDeclaration>

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

<Options>/<ObjectRootElementName>

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

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

<Options>/<Indent>

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

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

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

הערות שימוש

סכימות

הפניה לשגיאה

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

שגיאות פריסה

משתני תקלות

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

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

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

מדיניות JSONtoXML

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

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

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