درحال مشاهده اسناد Apigee Edge هستید.
به
اسناد Apigee X بروید. اطلاعات
چه
این خطمشی پیامها را از قالب «نشانگذاری شیء جاوا اسکریپت» (JSON) به زبان نشانهگذاری توسعهپذیر (XML) تبدیل میکند و چندین گزینه برای کنترل نحوه تبدیل پیامها دراختیارتان قرار میدهد.
این خطمشی بهویژه اگر بخواهید پیامها را بااستفاده از XSL تبدیل کنید مفید است. پساز تبدیل کردن بار JSON به XML، از خطمشی «تبدیل XSL» با برگ سبک سفارشی برای انجام تبدیل موردنیازتان استفاده کنید.
با فرض اینکه هدف تبدیل درخواست با قالب JSON به درخواست با قالب XML باشد، خطمشی به «جریان» درخواست پیوست میشود (برای نمونه، Request / ProxyEndpoint / PostFlow).
نمونهها
برای بحث مفصل درباره تبدیل بین JSON و XML، به مشکل تبدیل آرایه JSON به آرایه XML در شیء پاسخ مراجعه کنید.
درحال تبدیل درخواست
<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 | نام داخلی سیاست. مقدار مشخصه در صورت تمایل، از عنصر | N/A | مورد نیاز |
continueOnError | برای بازگرداندن خطا در صورت شکست خط مشی، روی روی | نادرست | اختیاری |
enabled | برای اجرای خط مشی روی برای خاموش کردن خط مشی، روی | درست است | اختیاری |
async | این ویژگی منسوخ شده است. | نادرست | منسوخ شده است |
عنصر <DisplayName>
علاوه بر ویژگی name برای برچسبگذاری خطمشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.
<DisplayName>Policy Display Name</DisplayName>
| پیش فرض | N/A اگر این عنصر را حذف کنید، از مقدار ویژگی |
|---|---|
| حضور | اختیاری |
| تایپ کنید | رشته |
عنصر <Source>
متغیر، درخواست، یا پاسخی که حاوی پیام JSON است و میخواهید آن را به XML تبدیل کنید.
اگر <Source> تعریف نشده باشد، بهعنوان پیام درنظر گرفته میشود (که وقتی خطمشی به جریان درخواست پیوست میشود به درخواست، یا وقتی خطمشی به جریان پاسخ پیوست میشود به پاسخ تبدیل میشود).
اگر متغیر منبع قابلحل نباشد یا به نوع غیرپیام حل شود، خطمشی خطا میدهد.
<Source>request</Source>
| پیشفرض | درخواست یا پاسخ، که براساس محل اضافه شدن خطمشی به جریان پراکسی API تعیین میشود |
| حضور | اختیاری |
| تایپ کردن | پیام |
عنصر <OutputVariable>
برونداد تبدیل قالب JSON به XML را ذخیره میکند. این معمولاً همان مقدار منبع است، یعنی معمولاً درخواست JSON به درخواست XML تبدیل میشود.
پایهبار پیام JSON تجزیه و به XML تبدیل میشود و سرایند HTTP Content-type
پیام با قالب XML روی text/xml;charset=UTF-8 تنظیم میشود.
اگر OutputVariable مشخص نشده باشد، source بهعنوان
OutputVariable درنظر گرفته میشود. برای مثال، اگر source برابر با request باشد،
آنگاه OutputVariable بهطور پیشفرض روی request تنظیم میشود.
<OutputVariable>request</OutputVariable>
| پیشفرض | درخواست یا پاسخ، که براساس محل اضافه شدن خطمشی به جریان پراکسی API تعیین میشود |
| حضور | وقتی متغیر تعریفشده در عنصر <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>
زبان نشانهگذاری توسعهپذیر حاصل بهصورت زیر نمایش داده میشود:
<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><Options>/<Indent>
مشخص میکند که برونداد زبان نشانهگذاری توسعهپذیر تورفتگی داشته باشد. مقدار پیشفرض 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>
{"person" : "I_AM_NULL"}به عنصر XML زیر:
<person></person>
اگر مقدار (یا مقداری غیر از I_AM_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 در جریان پاسخ خروجی جفت میشود. با ترکیب کردن خطمشیها به این روش، «میانای برنامهسازی کاربردی JSON» میتواند برای سرویسهایی که بهطور بومی فقط از XML پشتیبانی میکنند عرضه شود.
اغلب مفید است که JSON پیشفرض (خالی) را به خطمشی XML اعمال کنید و عناصر پیکربندی را بهصورت تکراری و درصورت نیاز اضافه کنید.
برای سناریوهایی که در آنها برنامههای مشتری متنوعی از «میاناهای برنامهسازی کاربردی» استفاده میکنند و ممکن است به JSON و XML نیاز داشته باشند، قالب پاسخ را میتوان با پیکربندی خطمشیهای تبدیل JSON به XML و XML به JSON برای اجرای شرطی بهصورت پویا تنظیم کرد. برای اجرای این سناریو، متغیرها و شرایط جریان را ببینید.
طرحوارهها
مرجع خطا
این بخش کدهای خطا و پیامهای خطایی را که برگردانده میشوند و متغیرهای خطایی را که Edge هنگام راهاندازی خطا در این خطمشی تنظیم میکند شرح میدهد. این اطلاعات برای دانستن اینکه آیا قوانین خطا را برای مدیریت خطاها توسعه میدهید یا نه مهم است. برای کسب اطلاعات بیشتر، آنچه باید درباره خطاهای خطمشی بدانیدو رسیدگی به اشکالات را ببینید.
خطاهای زمان اجرا
این خطاها ممکن است هنگام اجرای خطمشی رخ دهند.
| کد خطا | وضعیت HTTP | علت | رفع اشکال |
|---|---|---|---|
steps.jsontoxml.ExecutionFailed |
۵۰۰ | پایهبار ورودی (JSON) خالی است یا ورودی (JSON) که به خطمشی JSON به XML ارسال شده است نامعتبر یا بدشکل است. | build |
steps.jsontoxml.InCompatibleTypes |
۵۰۰ | این خطا زمانی رخ میدهد که نوع متغیر تعریفشده در عنصر <Source> و عنصر <OutputVariable> یکسان نباشد. الزامی است که نوع متغیرهای
موجود در عنصر <Source> و عنصر <OutputVariable>
مطابقت داشته باشد. انواع معتبر عبارتاند از message و string. |
build |
steps.jsontoxml.InvalidSourceType |
۵۰۰ | اگر نوع متغیر استفادهشده برای تعریف عنصر <Source> نامعتبر باشد، این خطا رخ میدهد. انواع معتبر متغیر message و string است. |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
۵۰۰ | این خطا زمانی رخ میدهد که متغیر مشخصشده در عنصر <Source> از JSON به
«خطمشی زبان نشانهگذاری توسعهپذیر» از نوع رشته باشد و عنصر <OutputVariable> تعریف نشده باشد.
وقتی متغیر تعریفشده در عنصر <Source>
از نوع رشته باشد، عنصر <OutputVariable> اجباری است. |
build |
steps.jsontoxml.SourceUnavailable |
۵۰۰ |
این خطا زمانی رخ میدهد که متغیر پیام
مشخصشده در عنصر <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