מדיניות JSONtoXML

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

מה

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

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

בהנחה שהכוונה היא להמיר בקשה בפורמט JSON לבקשה בפורמט XML, המדיניות תצורף לתהליך הבקשה (לדוגמה, Request / 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>

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


הפניה לרכיב

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

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

לא רלוונטי נדרש
continueOnError

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

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

false אופציונלי
enabled

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

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

true אופציונלי
async

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

false הוצא משימוש

רכיב <DisplayName>

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

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

לא רלוונטי

אם משמיטים את הרכיב הזה, המערכת משתמשת בערך של מאפיין name של המדיניות.

נוכחות אופציונלי
תיאור מחרוזת

רכיב <Source>

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

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

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

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

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

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

<אפשרויות>/<כניסה>

מציינת את כניסת הפיסקה בפלט ה-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.

לדוגמה:

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

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

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

סכימות

הפניה לשגיאות

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

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

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

קוד שגיאה סטטוס HTTP סיבה תיקון
steps.jsontoxml.ExecutionFailed 500 המטען הייעודי (payload) של הקלט (JSON) ריק או שהקלט (JSON) שהועבר למדיניות JSON ל-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

דוגמה לשגיאה

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

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