Правило JSONtoXML

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

Что

Это правило преобразует письма из формата JSON (JavaScript Object Notation) в формат XML (extensible markup language). При этом у вас будет несколько вариантов управления процессом преобразования.

Правило особенно полезно, если вы хотите преобразовать письма с помощью XSL. После преобразования полезной нагрузки JSON в XML используйте правило преобразования XSL с пользовательской таблицей стилей, чтобы выполнить необходимое преобразование.

Если вы хотите преобразовать запрос в формате JSON в запрос в формате XML, правило нужно прикрепить к потоку запроса (например, Request / ProxyEndpoint / PostFlow).

Примеры

Подробную информацию о преобразовании JSON в XML можно найти в статье Проблема с преобразованием массива JSON в массив XML в объекте ответа.

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

Сведения об элементах

Ниже перечислены элементы и атрибуты, которые можно настроить в этом правиле.

<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1">
    <DisplayName>JSON to XML 1</DisplayName>
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
    <Options>
        <OmitXmlDeclaration>false</OmitXmlDeclaration>
        <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
        <NamespaceSeparator>:</NamespaceSeparator>
        <AttributeBlockName>#attrs</AttributeBlockName>
        <AttributePrefix>@</AttributePrefix>
        <ObjectRootElementName>Root</ObjectRootElementName>
        <ArrayRootElementName>Array</ArrayRootElementName>
        <ArrayItemElementName>Item</ArrayItemElementName>
        <Indent>false</Indent>
        <TextNodeName>#text</TextNodeName>
        <NullValue>I_AM_NULL</NullValue>
        <InvalidCharsReplacement>_</InvalidCharsReplacement>
    </Options>
</JSONToXML>

Атрибуты <JSONToXML>

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

Элемент <Source>

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

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

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

<Source>request</Source>

Элемент <OutputVariable>

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

Полезная нагрузка сообщения JSON анализируется и преобразуется в XML, а для заголовка HTTP Content-type сообщения в формате XML задается значение text/xml;charset=UTF-8.

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

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

Указывает, что пространство имен XML должно быть исключено из выходных данных. Значение по умолчанию – false, то есть пространство имен будет включено в выходные данные.

Например, следующая настройка позволяет исключить пространство имен из политики:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

JSON не поддерживает пространства имен, а XML-документы часто требуют их. NamespaceBlockName позволяет определить свойство JSON, которое будет источником определения пространства имен в XML, созданном правилом. (Это означает, что в исходном файле JSON должен быть ресурс, который можно сопоставить с пространством имен, ожидаемым приложением, использующим полученный XML-файл.)

Например, следующие настройки:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

указывает, что в исходном файле JSON есть свойство #namespaces, которое содержит хотя бы одно пространство имен, назначенное по умолчанию. Пример:

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

будет преобразовано в:

<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers">
  <person>John Smith</person>
  <exp:person>Pedro Cabral</exp:person>
</population>

<Options>/<ObjectRootElementName>

<ObjectRootElementName> указывает название корневого элемента при преобразовании из JSON, в котором нет корневого элемента с названием, в XML.

Например, если JSON выглядит так:

{
  "abc": "123",
  "efg": "234"
}

Вы задали для элемента <ObjectRootElementName> следующее значение:

<ObjectRootElementName>Root</ObjectRootElementName>

Полученный XML-код выглядит следующим образом:

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

Элементы <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

<AttributeBlockName> позволяет указать, когда элементы JSON должны преобразовываться в атрибуты XML (а не в элементы XML).

Например, следующая настройка преобразует свойства объекта #attrs в атрибуты XML:

<AttributeBlockName>#attrs</AttributeBlockName>

Следующий объект JSON:

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },
        "occupation" : "explorer",
    }
}

преобразуется в следующую структуру XML:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<AttributePrefix> преобразует свойство, начинающееся с указанного префикса, в атрибуты XML. Если префикс атрибута задан как @, например:

<AttributePrefix>@</AttributePrefix>

Преобразует следующий объект JSON:

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

в следующую структуру XML:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

Элемент <Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName>

Преобразует массив JSON в список элементов XML с указанными названиями родительских и дочерних элементов.

Например, следующие настройки:

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

преобразует следующий массив JSON:

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

в следующую структуру XML:

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

<Options>/<Indent>

Указывает, что выходные данные XML должны быть отформатированы с отступами. Значение по умолчанию – false (без отступа).

Например, следующая настройка задает отступ в выходных данных:

<Indent>true</Indent>

Если входные данные JSON имеют следующий вид:

{"n": [1, 2, 3] }

Тогда результат без отступов будет выглядеть так:

<Array><n>1</n><n>2</n><n>3</n></Array>

Если включить отступы, результат будет выглядеть так:

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

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

Преобразует свойство JSON в текстовый узел XML с указанным именем. Например, если задана следующая настройка:

<TextNodeName>age</TextNodeName>

преобразует следующий код JSON:

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

в следующую структуру XML:

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

Если TextNodeName не указан, XML-код создается с использованием настройки по умолчанию для текстового узла:

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

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

Указывает на нулевое значение. По умолчанию задано значение NULL.

Например, можно задать следующие настройки:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

следующему XML-элементу:

<person></person>

Если для нулевого значения не указано значение (или указано значение, отличное от I_AM_NULL), то та же полезная нагрузка преобразуется в:

<person>I_AM_NULL</person>

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

Чтобы помочь с обработкой недопустимого XML-кода, который может вызвать проблемы с синтаксическим анализатором, этот параметр заменяет любые элементы JSON, которые создают недопустимый XML-код, на строку. Например, можно задать следующие настройки:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Преобразует этот объект JSON

{
    "First%%%Name": "John"
}

в следующую структуру XML:

<First_Name>John<First_Name>

Примечания

В типичном сценарии медиации правило JSON в XML для входящего запроса часто сочетается с правилом XML в JSON для исходящего ответа. Таким образом можно объединить правила и создать JSON API для сервисов, которые изначально поддерживают только XML.

Часто бывает полезно применить к правилу JSON для XML пустой JSON по умолчанию и итеративно добавлять элементы конфигурации по мере необходимости.

Если API используются разными клиентскими приложениями, которым могут требоваться форматы JSON и XML, формат ответа можно задать динамически, настроив правила преобразования JSON в XML и XML в JSON для условного выполнения. Пример реализации этого сценария можно найти в разделе Переменные и условия.

Схемы

Справочник по ошибкам

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые задаются Edge, когда это правило вызывает ошибку. Эта информация важна, если вы разрабатываете правила обработки ошибок. Подробнее о том, что нужно знать об ошибках в правилах и об обработке ошибок…

Ошибки времени выполнения

Эти ошибки могут возникать при выполнении правил.

Ошибки развертывания

Нет.

Переменные ошибок

Эти переменные задаются при возникновении ошибки выполнения. Подробнее о нарушениях правил…

Пример ответа об ошибке

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Пример правила обработки ошибок

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

Статьи по теме

• XML в JSON: правило "XML в JSON".
• Преобразование XSL: правила преобразования XSL.