политика 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>

Схемы

Ссылка на ошибку

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются 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