политика XMLtoJSON

Вы просматриваете документацию Apigee Edge .
Перейдите в документацию Apigee X.info

Что

Данная политика преобразует сообщения из формата расширяемого языка разметки (XML) в формат JSON (JavaScript Object Notation), предоставляя вам несколько вариантов управления процессом преобразования сообщений.

Предположим, что цель состоит в преобразовании ответа в формате XML в ответ в формате JSON. В этом случае политика будет прикреплена к потоку обработки ответов (например, Response / ProxyEndpoint / PostFlow).

О

В типичном сценарии посредничества политика преобразования JSON в XML для входящего потока запросов часто сочетается с политикой преобразования XML в JSON для исходящего потока ответов. Комбинируя политики таким образом, можно предоставить доступ к JSON API для бэкэнд-сервисов, которые изначально поддерживают только 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>

<Исходный> элемент

Переменная, request или response, содержащая XML-сообщение, которое вы хотите преобразовать в JSON.

В заголовке HTTP Content-type исходного сообщения необходимо установить значение application/xml , в противном случае политика не будет применяться.

Если <Source> не определен, то он рассматривается как сообщение (которое преобразуется в запрос, когда политика прикреплена к потоку запросов, или в ответ, когда политика прикреплена к потоку ответов).

Если исходная переменная не может быть разрешена или имеет тип, отличный от сообщения, политика выдает ошибку.

<Source>response</Source>

элемент <OutputVariable>

Сохраняет результат преобразования XML в JSON. Обычно это то же значение, что и в исходном файле, то есть, как правило, XML-ответ преобразуется в JSON-ответ.

Содержимое XML-сообщения анализируется и преобразуется в JSON, а заголовок HTTP Content-type XML-отформатированного сообщения устанавливается в application/json .

Если OutputVariable не указан, source рассматривается как OutputVariable . Например, если source является response , то по умолчанию OutputVariable принимает значение response .

<OutputVariable>response</OutputVariable>

<Параметры>

Параметры позволяют управлять преобразованием из XML в JSON. Используйте либо группу <Options> , которая позволяет добавлять конкретные параметры преобразования, либо элемент <Format> , который позволяет ссылаться на шаблон предопределенных параметров. Нельзя использовать одновременно <Options> и <Format> .

<Options> необходим, если <Format> не используется.

Элемент <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> элемент

Позволяет преобразованию сохранять логические значения true/false, а не преобразовывать их в строки.

<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> элемент

Позволяет преобразовывать пустые значения в значения NULL.

<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>/<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>/<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
                        }  ...

В этом примере третий уровень — это 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: Учебное пособие для сообщества: Опция 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>

Google

<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