خط مشی XMLtoJSON

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

چه

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

با فرض اینکه هدف تبدیل یک پاسخ با فرمت XML به یک پاسخ با فرمت JSON باشد، این سیاست به یک جریان پاسخ (برای مثال، Response / ProxyEndpoint / PostFlow) متصل می‌شود.

درباره ما

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

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

نمونه‌ها

برای بحث مفصل در مورد تبدیل بین JSON و XML، به تبدیل بین XML و JSON با Apigee: آنچه باید بدانید مراجعه کنید.

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

مرجع عنصر

در ادامه عناصر و ویژگی‌هایی که می‌توانید در این سیاست پیکربندی کنید، آمده است.

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</DisplayName>
    <Source>response</Source>
    <OutputVariable>response</OutputVariable>
    <Options>
        <RecognizeNumber>true</RecognizeNumber>
        <RecognizeBoolean>true</RecognizeBoolean>
        <RecognizeNull>true</RecognizeNull>
        <NullValue>NULL</NullValue>
        <NamespaceBlockName>#namespaces</NamespaceBlockName>
        <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
        <NamespaceSeparator>***</NamespaceSeparator>
        <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
        <TextNodeName>TEXT</TextNodeName>
        <AttributeBlockName>FOO_BLOCK</AttributeBlockName>
        <AttributePrefix>BAR_</AttributePrefix>
        <OutputPrefix>PREFIX_</OutputPrefix>
        <OutputSuffix>_SUFFIX</OutputSuffix>
        <StripLevels>2</StripLevels>
        <TreatAsArray>
            <Path unwrap="true">teachers/teacher/studentnames/name</Path>
        </TreatAsArray>
    </Options>
    <!-- Use Options or Format, not both -->
    <Format>yahoo</Format>
</XMLToJSON>

ویژگی‌های <XMLtoJSON>

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

عنصر <منبع>

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

هدر نوع محتوای HTTP پیام منبع باید روی application/xml تنظیم شود، در غیر این صورت این خط‌مشی اجرا نمی‌شود.

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

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

<Source>response</Source>

عنصر <متغیر خروجی>

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

محتوای پیام XML تجزیه و به JSON تبدیل می‌شود و هدر نوع محتوای HTTP پیام با فرمت XML روی application/json تنظیم می‌شود.

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

<OutputVariable>response</OutputVariable>

<گزینه‌ها>

گزینه‌ها به شما امکان کنترل تبدیل از XML به JSON را می‌دهند. یا از گروه <Options> استفاده کنید که به شما امکان می‌دهد تنظیمات تبدیل خاصی را اضافه کنید، یا از عنصر <Format> استفاده کنید که به شما امکان می‌دهد به الگویی از گزینه‌های از پیش تعریف شده ارجاع دهید. نمی‌توانید از هر دو <Options> و <Format> استفاده کنید.

اگر <Format> استفاده نشود، <Options> الزامی است.

عنصر <Options>/<RecognizeNumber>

اگر درست باشد، فیلدهای عددی در فایل XML قالب اصلی خود را حفظ می‌کنند.

<RecognizeNumber>true</RecognizeNumber>

مثال XML زیر را در نظر بگیرید:

<a>
  <b>100</b>
  <c>value</c>
</a>

اگر true ، به این تبدیل می‌شود:

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

اگر false ، به این تبدیل می‌شود:

{
    "a": {
        "b": "100",
        "c": "value"
    }
}

عنصر <Options>/<RecognizeBoolean>

به تبدیل اجازه می‌دهد تا مقادیر بولی درست/نادرست را حفظ کند، نه اینکه آنها را به رشته تبدیل کند.

<RecognizeBoolean>true</RecognizeBoolean>

برای مثال XML زیر:

<a>
  <b>true</b>
  <c>value</c>
</a>

اگر true ، به این تبدیل می‌شود:

{
    "a": {
        "b": true,
        "c": "value"
    }
}

اگر false ، به این تبدیل می‌شود:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

عنصر <Options>/<RecognizeNull>

به شما امکان می‌دهد مقادیر خالی را به مقادیر تهی تبدیل کنید.

<RecognizeNull>true</RecognizeNull>

برای XML زیر:

<a>
  <b></b>
  <c>value</c>
</a>

اگر true ، به این تبدیل می‌شود:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

اگر false ، به این تبدیل می‌شود:

{
  "a": {
    "b": {},
    "c": "value"
  }
}

عنصر <Options>/<NullValue>

مقداری را نشان می‌دهد که مقادیر تهیِ شناخته‌شده در پیام منبع باید به آن تبدیل شوند. به طور پیش‌فرض، این مقدار null است. این گزینه فقط در صورتی مؤثر است که RecognizeNull برابر با true باشد.

<NullValue>not-present</NullValue>

<گزینه‌ها>/<نام‌فضای‌بلوک>
<گزینه‌ها>/<نام پیش‌فرضفضای‌گره‌نام>
عناصر <Options>/<NamespaceSeparator>

از این عناصر در کنار هم استفاده کنید.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
<NamespaceSeparator>***</NamespaceSeparator>

مثال XML زیر را در نظر بگیرید:

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">
  <ns1:b>value</ns1:b>
</a>

اگر NamespaceSeparator مشخص نشده باشد، ساختار JSON زیر تولید می‌شود:

{
    "a": {
        "b": "value"
    }
}

اگر عناصر NamespaceBlockName ، DefaultNamespaceNodeName و NamespaceSeparator به ترتیب به صورت #namespaces ، & و *** مشخص شوند، ساختار JSON زیر تولید می‌شود:

{
    "a": {
        "#namespaces": {
            "&": "http://ns.com",
            "ns1": "http://ns1.com"
        },
        "ns1***b": "value"
    }
}

<گزینه‌ها>/<متن همیشه به عنوان ویژگی>
عناصر <Options>/<TextNodeName>

از این عناصر در کنار هم استفاده کنید.

اگر روی true تنظیم شود، محتوای عنصر XML به یک ویژگی رشته‌ای تبدیل می‌شود.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

برای XML زیر:

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

اگر TextAlwaysAsProperty روی true تنظیم شده باشد و TextNodeName با TEXT مشخص شده باشد، ساختار JSON زیر تولید می‌شود:

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

اگر TextAlwaysAsProperty روی false تنظیم شده باشد و TextNodeName با TEXT مشخص شده باشد، ساختار JSON زیر تولید می‌شود:

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}

<گزینه‌ها>/<نام بلوک ویژگی>
عناصر <Options>/<AttributePrefix>

از این عناصر در کنار هم استفاده کنید.

به شما امکان می‌دهد مقادیر را در یک بلوک JSON گروه‌بندی کنید و پیشوندها را به نام ویژگی‌ها اضافه کنید.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName>
<AttributePrefix>BAR_</AttributePrefix>

مثال XML زیر را در نظر بگیرید:

<a attrib1="value1" attrib2="value2"/>

اگر هر دو ویژگی ( AttributeBlockName و AttributePrefix ) همانطور که در مثال XML به JSON تعریف شده است، مشخص شوند، ساختار JSON زیر تولید می‌شود:

{
  "a": {
    "FOO_BLOCK": {
      "BAR_attrib1": "value1",
      "BAR_attrib2": "value2"
    }
  }
}

اگر فقط AttributeBlockName مشخص شود، ساختار JSON زیر تولید می‌شود:

{
    "a": {
        "FOO_BLOCK": {
            "attrib1": "value1",
            "attrib2": "value2"
        }
    }
}

اگر فقط AttributePrefix مشخص شود، ساختار JSON زیر تولید می‌شود:

{
    "a": {
        "BAR_attrib1": "value1",
        "BAR_attrib2": "value2"
    }
}

اگر هیچ‌کدام مشخص نشود، ساختار JSON زیر تولید می‌شود:

{
    "a": {
        "attrib1": "value1",
        "attrib2": "value2"
    }
}

<گزینه‌ها>/<پیشوند خروجی>
عناصر <Options>/<OutputSuffix>

از این عناصر در کنار هم استفاده کنید.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

مثال XML زیر را در نظر بگیرید:

<a>value</a>

اگر هر دو ویژگی ( OutputPrefix و OutputSuffix ) همانطور که در مثال XML to JSON تعریف شده است، مشخص شوند، ساختار JSON زیر تولید می‌شود:

PREFIX_{
    "a": "value"
}_SUFFIX

اگر فقط OutputPrefix مشخص شود، ساختار JSON زیر تولید می‌شود:

PREFIX_{
  "a" : "value"
}

اگر فقط OutputSuffix مشخص شود، ساختار JSON زیر تولید می‌شود:

{
  "a" : "value"
}_SUFFIX

اگر هیچ یک OutputPrefix و OutputSuffix مشخص نشده باشند، ساختار JSON زیر تولید می‌شود:

{
    "a": "value"
}

عنصر <Options>/<StripLevels>

<Options>
    <StripLevels>4</StripLevels>
</Options>

گاهی اوقات فایل‌های XML مانند SOAP، سطوح والد زیادی دارند که نمی‌خواهید در JSON تبدیل‌شده لحاظ شوند. در اینجا یک مثال از پاسخ SOAP که شامل سطوح زیادی است، آورده شده است:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
          <GetCityWeatherByZIPResult>
              <State>CO</State>
              <City>Denver</City>
              <Description>Sunny</Description>
              <Temperature>62</Temperature>
          </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
  </soap:Body>
</soap:Envelope>

قبل از رسیدن به سطح استان، شهر، توضیحات و دما، ۴ سطح وجود دارد. بدون استفاده از <StripLevels> ، پاسخ JSON تبدیل شده به این شکل خواهد بود:

{
   "Envelope" : {
      "Body" : {
         "GetCityWeatherByZIPResponse" : {
            "GetCityWeatherByZIPResult" : {
               "State" : "CO",
               "City" : "Denver",
               "Description" : "Sunny",
               "Temperature" : "62"
            }
         }
      }
   }
}

اگر می‌خواهید آن ۴ سطح اول را در پاسخ JSON حذف کنید، باید <StripLevels>4</StripLevels> را تنظیم کنید که JSON زیر را به شما می‌دهد:

{
  "State" : "CO",
  "City" : "Denver",
  "Description" : "Sunny",
  "Temperature" : "62"
}

شما می‌توانید سطوح را تا اولین عنصری که شامل چندین فرزند است، حذف کنید. این به چه معناست؟ بیایید به یک مثال پیچیده‌تر JSON نگاه کنیم:

{
   "Envelope" : {
      "Body" : {
         "GetCityForecastByZIPResponse" : {
            "GetCityForecastByZIPResult" : {
               "ResponseText" : "City Found",
               "ForecastResult" : {
                  "Forecast" : [
                     {
                        "ProbabilityOfPrecipiation" : {
                           "Nighttime" : "00",
                           "Daytime" : 10
                        }  ...

سطح ۳ در این مثال GetCityForecastByZIPResponse است که فقط یک فرزند دارد. بنابراین اگر <StripLevels>3</StripLevels> استفاده کنید (سه سطح اول را حذف کنید)، JSON به این شکل خواهد بود:

{
   "GetCityForecastByZIPResult" : {
      "ResponseText" : "City Found",
      "ForecastResult" : {
         "Forecast" : [
            {
               "ProbabilityOfPrecipiation" : {
                  "Nighttime" : "00",
                  "Daytime" : 10
               }  ...

توجه داشته باشید که GetCityForecastByZIPResult چندین فرزند دارد. از آنجایی که این اولین عنصری است که شامل چندین فرزند می‌شود، می‌توانید این آخرین سطح را با استفاده از <StripLevels>4</StripLevels> حذف کنید، که JSON زیر را به شما می‌دهد:

{
   "ResponseText" : "City Found",
   "ForecastResult" : {
      "Forecast" : [
         {
            "ProbabilityOfPrecipiation" : {
               "Nighttime" : "00",
               "Daytime" : 10
            }  ...

از آنجا که سطح ۴ اولین سطحی است که شامل چندین فرزند می‌شود، نمی‌توانید سطوح پایین‌تر از این را حذف کنید. اگر سطح حذف را روی ۵، ۶، ۷ و غیره تنظیم کنید، همچنان پاسخ بالا را دریافت خواهید کرد.

عنصر <Options>/<TreatAsArray>/<Path>

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

این ترکیب عنصر به شما امکان می‌دهد مطمئن شوید که مقادیر یک سند XML در یک آرایه JSON قرار می‌گیرند. این مفید است، برای مثال، زمانی که تعداد عناصر فرزند می‌تواند متفاوت باشد (از یک تا چند) و می‌خواهید مطمئن شوید که مقادیر همیشه در یک آرایه هستند. انجام این کار به پایدار نگه داشتن کد شما کمک می‌کند، زیرا می‌توانید داده‌ها را از آرایه هر بار به یک روش دریافت کنید. به عنوان مثال: $.teachers.teacher.studentnames[0] مقدار نام اولین دانش‌آموز را در آرایه صرف نظر از تعداد مقادیر موجود در آرایه دریافت می‌کند.

بیایید یک قدم به عقب برگردیم و به رفتار پیش‌فرض XML به JSON نگاهی بیندازیم، سپس نحوه کنترل خروجی را با استفاده از <TreatAsArray>/<Path> بررسی کنیم.

وقتی یک سند XML شامل عنصری با چندین مقدار فرزند باشد (معمولاً بر اساس طرحی که در آن maxOccurs='unbounded' عنصر قرار دارد)، سیاست XML to JSON به طور خودکار آن مقادیر را در یک آرایه قرار می‌دهد. به عنوان مثال، بلوک XML زیر

<teacher>
    <name>teacherA</name>
    <studentnames>
        <name>student1</name>
        <name>student2</name>
    </studentnames>
</teacher>

... به طور خودکار و بدون هیچ پیکربندی خاصی به JSON زیر تبدیل می‌شود:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}
           }
      }
}

توجه کنید که نام دو دانش‌آموز در یک آرایه قرار داده شده است.

با این حال، اگر فقط یک دانشجو در سند XML ظاهر شود، سیاست XML to JSON به طور خودکار با مقدار به عنوان یک رشته واحد، نه آرایه‌ای از رشته‌ها، رفتار می‌کند، همانطور که در مثال زیر نشان داده شده است:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : "student1"
              }
          }
      }
}

در مثال‌های قبلی، داده‌های مشابه به طور متفاوتی تبدیل می‌شدند، یک بار به صورت آرایه و بار دیگر به صورت یک رشته. اینجاست که عنصر <TreatAsArray>/<Path> به شما امکان کنترل خروجی را می‌دهد. برای مثال، می‌توانید مطمئن شوید که نام دانش‌آموزان همیشه در یک آرایه قرار می‌گیرد، حتی اگر فقط یک مقدار وجود داشته باشد. شما این کار را با مشخص کردن مسیر عنصری که می‌خواهید مقادیر آن را در یک آرایه قرار دهید، پیکربندی می‌کنید، مانند این:

<Options>
    <TreatAsArray>
        <Path>teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

پیکربندی بالا، JSON را به این شکل می‌نویسد:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : ["student1"]
              }
            ]
          }
      }
}

توجه کنید که student1 اکنون در یک آرایه قرار دارد. اکنون، صرف نظر از اینکه یک یا چند دانش‌آموز وجود دارد، می‌توانید آنها را از یک آرایه JSON در کد خود با استفاده از JSONPath زیر بازیابی کنید: $.teachers.teacher.studentnames.name[0]

عنصر <Path> همچنین دارای یک ویژگی unwrap است که در بخش بعدی توضیح داده شده است.

ویژگی‌ها

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

برای مثال‌های بیشتر و بررسی ویژگی‌ها، به این مقاله انجمن Apigee با عنوان « آموزش انجمن: گزینه TreatAsArray در سیاست XML به JSON» مراجعه کنید.

قالب‌بندی

قالب به شما امکان کنترل تبدیل XML به JSON را می‌دهد. نام یک قالب از پیش تعریف شده را که شامل ترکیبی خاص از عناصر Options شرح داده شده در این موضوع است، وارد کنید. قالب‌های از پیش تعریف شده عبارتند از: xml.com ، yahoo ، google ، badgerFish .

یا از عنصر <Format> یا از گروه <Options> استفاده کنید. نمی‌توانید از هر دو <Format> و <Options> استفاده کنید.

در ادامه تعاریف قالب هر الگوی از پیش تعریف شده آمده است.

xml.com

<RecognizeNull>true</RecognizeNull>
<TextNodeName>#text</TextNodeName>
<AttributePrefix>@</AttributePrefix>

یاهو

<RecognizeNumber>true</RecognizeNumber>
<TextNodeName>content</TextNodeName>

گوگل

<TextNodeName>$t</TextNodeName>
<NamespaceSeparator>$</NamespaceSeparator>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>

گورکن

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

نحو عنصر:

<Format>yahoo</Format>

طرحواره‌ها

مرجع خطا

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

These errors can occur when you deploy a proxy containing this policy.

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": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Example fault rule

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

مباحث مرتبط

تبدیل JSON به XML: سیاست تبدیل JSON به XML