כרגע מוצג התיעוד של 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 |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש באלמנט |
לא רלוונטי | נדרש |
continueOnError |
צריך להגדיר את הערך צריך להגדיר את הערך |
false | אופציונלי |
enabled |
צריך להגדיר את הערך צריך להגדיר את הערך |
true | אופציונלי |
async |
המאפיין הזה הוצא משימוש. |
false | הוצא משימוש |
רכיב <DisplayName>
יש להשתמש במאפיין הזה בנוסף למאפיין name
כדי להוסיף למדיניות
בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם אחר בשפה טבעית.
<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, המערכת משתמשת בערך של מאפיין |
---|---|
נוכחות | אופציונלי |
תיאור | מחרוזת |
רכיב <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 לא חוקי או פגום. | build |
steps.jsontoxml.InCompatibleTypes |
500 | השגיאה הזו מתרחשת אם סוג המשתנה שמוגדר ברכיב <Source> והרכיב <OutputVariable> לא זהים. חובה להקפיד על התאמה בין סוג המשתנים שכלולים ברכיב <Source> לבין סוג המשתנה <OutputVariable> . הסוגים החוקיים הם message ו-string . |
build |
steps.jsontoxml.InvalidSourceType |
500 | השגיאה הזו מתרחשת אם סוג המשתנה שמשמש להגדרת הרכיב <Source>
לא תקין. סוגי המשתנים החוקיים הם message ו-string . |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 | השגיאה הזו מתרחשת אם המשתנה שצוין ברכיב <Source> של מדיניות JSON ל-XML הוא מסוג מחרוזת והרכיב <OutputVariable> לא מוגדר.
הרכיב <OutputVariable> הוא שדה חובה כשהמשתנה שמוגדר ברכיב <Source> הוא מסוג מחרוזת. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
השגיאה הזו מתרחשת אם המשתנה message
שמצוין ברכיב <Source> של מדיניות JSON ל-XML הוא:
|
build |
שגיאות בפריסה
ללא.
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
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>
נושאים קשורים
- XML ל-JSON: מדיניות מ-XML ל-JSON
- טרנספורמציה של XSL: מדיניות XSL Transform