политика XMLtoJSON

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

Что

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

Предполагая, что целью является преобразование ответа в формате 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>

Элемент <Источник>

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

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

<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 в исходном сообщении. По умолчанию значение равно 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"
    }
}

<Параметры>/<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>/<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
                        }  ...

Уровень 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: Учебное пособие сообщества: параметр 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>

yahoo

<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