خط مشی JSONtoXML

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

چی

این خط‌مشی پیام‌ها را از فرمت نشانه‌گذاری شی جاوا اسکریپت (JSON) به زبان نشانه‌گذاری قابل توسعه (XML) تبدیل می‌کند و چندین گزینه برای کنترل نحوه تبدیل پیام‌ها در اختیار شما قرار می‌دهد.

این خط مشی مخصوصاً در صورتی مفید است که می خواهید پیام ها را با استفاده از XSL تغییر دهید. پس از تبدیل یک بار 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>

مرجع عنصر

در زیر عناصر و ویژگی هایی وجود دارد که می توانید در این خط مشی پیکربندی کنید.

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

عنصر <منبع>

متغیر، درخواست یا پاسخ که حاوی پیام JSON است که می‌خواهید به XML تبدیل کنید.

اگر <Source> تعریف نشده باشد، به عنوان پیام تلقی می‌شود (که وقتی خط‌مشی به جریان درخواست پیوست می‌شود، درخواست می‌کند، یا زمانی که خط‌مشی به جریان پاسخ متصل می‌شود، پاسخ می‌دهد).

اگر متغیر منبع قابل حل نباشد، یا به یک نوع غیر پیامی تبدیل شود، خط مشی خطایی ایجاد می کند.

<Source>request</Source>

عنصر <OutputVariable>

خروجی تبدیل فرمت JSON به XML را ذخیره می کند. این مقدار معمولاً همان مقدار منبع است، یعنی معمولاً درخواست JSON به درخواست XML تبدیل می شود.

بار پیام JSON تجزیه و به XML تبدیل می‌شود، و هدر نوع محتوای HTTP پیام با قالب‌بندی XML روی text/xml;charset=UTF-8 تنظیم می‌شود.

اگر OutputVariable مشخص نشده باشد، source به عنوان OutputVariable در نظر گرفته می شود. به عنوان مثال، اگر source request است، سپس OutputVariable به طور پیش فرض request می کند.

<OutputVariable>request</OutputVariable>

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

<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 است.

به عنوان مثال تنظیمات زیر:

<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 در جریان درخواست ورودی اغلب با یک خط مشی XMLtoJSON در جریان پاسخ خروجی جفت می شود. با ترکیب خط‌مشی‌ها از این طریق، یک JSON API می‌تواند برای سرویس‌هایی که به صورت بومی فقط از XML پشتیبانی می‌کنند، در معرض دید قرار گیرد.

استفاده از JSON پیش‌فرض (خالی) در خط‌مشی XML و افزودن مکرر عناصر پیکربندی در صورت لزوم، اغلب مفید است.

برای سناریوهایی که در آن APIها توسط برنامه‌های کلاینت‌های متنوعی مصرف می‌شوند که ممکن است به JSON و XML نیاز داشته باشند، قالب پاسخ را می‌توان به صورت پویا با پیکربندی سیاست‌های JSON به XML و XML به JSON برای اجرای مشروط تنظیم کرد. متغیرهای جریان و شرایط را برای اجرای این سناریو ببینید.

طرحواره ها

مرجع خطا

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

<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