Правило XMLtoJSON

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

Что

Это правило преобразует письма из формата 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 и наоборот можно найти в статье Converting between XML and JSON with Apigee: What you need to know (Преобразование 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>

Элемент <Source>

Переменная, запрос или ответ, содержащие сообщение 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>

<Options>

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

<Options> указывать обязательно, если <Format> отсутствует.

Элемент <Options>/<RecognizeNumber>

Если значение равно true, то числовые поля в полезной нагрузке 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>/<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>

До уровня "Штат, город, описание и температура" есть четыре уровня. Без использования <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
                        }  ...

Уровень 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 Community tutorial: The TreatAsArray option in the XML to JSON policy (Руководство сообщества: параметр TreatAsArray в правилах преобразования XML в JSON).

<Format>

Параметр "Формат" позволяет управлять преобразованием из XML в JSON. Введите название готового шаблона, содержащего определенную комбинацию элементов Options, описанных в этом разделе. К предопределенным форматам относятся: xml.com, yahoo, google, badgerFish.

Используйте элемент <Format> или группу <Options>. Нельзя использовать одновременно <Format> и <Options>.

Ниже приведены определения формата для каждого из стандартных шаблонов.

xml.com

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

Yahoo

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

google

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

badgerFish

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