מדיניות JSONtoXML

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

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

המדיניות JSONtoXML ממירה הודעות מפורמט אובייקט ב-JavaScript ‏ (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>

הפניה לרכיב

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

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

<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 מהפלט. שורה של הצהרת 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>

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

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

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

שגיאות בהטמעה

אין.

משתני תקלות

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

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

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