خط مشی XMLtoJSON

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

چی

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

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

درباره

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

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

نمونه ها

برای بحث مفصل در مورد تبدیل بین JSON و XML، به http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html مراجعه کنید.

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

عنصر <OutputVariable>

خروجی تبدیل فرمت 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 درست باشد.

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
عناصر <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>/<TextAlwaysAsProperty>
عناصر <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>/<AttributeBlockName>
عناصر <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>/<OutputPrefix>
عناصر <Options>/<OutputSuffix>

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

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

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

<a>value</a>

اگر هر دو ویژگی ( OutputPrefix و OutputSuffix ) همانطور که در مثال XML به 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>

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

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

اگر می‌خواهید آن 4 سطح اول را در پاسخ 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
                        }  ...

سطح 3 در این مثال 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
            }  ...

از آنجایی که سطح 4 اولین سطح شامل چند فرزند است، نمی‌توانید هیچ سطحی را پایین‌تر از این حذف کنید. اگر سطح نوار را روی 5، 6، 7 و غیره تنظیم کنید، همچنان پاسخ بالا را دریافت خواهید کرد.

عنصر <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 به 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 به 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 را ببینید: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html .

<فرمت>

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

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

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

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>

طرحواره ها

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که یک خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

نمونه پاسخ خطا

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

مثال قانون خطا

<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