خط‌مشی JSONtoXML

درحال مشاهده اسناد 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

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

درست است اختیاری
async

این ویژگی منسوخ شده است.

نادرست منسوخ شده است

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

عنصر <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>
شیء JSON زیر را تبدیل می‌کند:
{"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 ارسال شده است نامعتبر یا بدشکل است.
steps.jsontoxml.InCompatibleTypes ۵۰۰ این خطا زمانی رخ می‌دهد که نوع متغیر تعریف‌شده در عنصر <Source> و عنصر <OutputVariable> یکسان نباشد. الزامی است که نوع متغیرهای موجود در عنصر <Source> و عنصر <OutputVariable> مطابقت داشته باشد. انواع معتبر عبارت‌اند از message و string.
steps.jsontoxml.InvalidSourceType ۵۰۰ اگر نوع متغیر استفاده‌شده برای تعریف عنصر <Source> نامعتبر باشد، این خطا رخ می‌دهد. انواع معتبر متغیر message و string است.
steps.jsontoxml.OutputVariableIsNotAvailable ۵۰۰ این خطا زمانی رخ می‌دهد که متغیر مشخص‌شده در عنصر <Source> از JSON به «خط‌مشی زبان نشانه‌گذاری توسعه‌پذیر» از نوع رشته باشد و عنصر <OutputVariable> تعریف نشده باشد. وقتی متغیر تعریف‌شده در عنصر <Source> از نوع رشته باشد، عنصر <OutputVariable> اجباری است.
steps.jsontoxml.SourceUnavailable ۵۰۰ این خطا زمانی رخ می‌دهد که متغیر پیام مشخص‌شده در عنصر <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>

موضوعات مرتبط