Политика JSONtoXML

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

Что

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

Эта политика особенно полезна, если вы хотите преобразовать сообщения с помощью 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>

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

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

<Параметры>/<ОпуститьXmlДекларацию>

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

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<Параметры>/<ИмяБлокаПространстваИмен>
<Параметры>/<ИмяУзлаПространстваИменПоУмолчанию>
Элементы <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>

<Параметры>/<ИмяКорневогоЭлементаОбъекта>

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

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

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

И вы устанавливаете <ObjectRootElementName> как:

<ObjectRootElementName>Root</ObjectRootElementName>

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

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

<Параметры>/<ИмяАтрибутБлока>
Элементы <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>/<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>

<Параметры>/<Отступ>

Задаёт отступ для 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>

Если для значения Null не указано значение (или указано значение, отличное от 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 и итеративно добавлять элементы конфигурации по мере необходимости.

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

Схемы

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

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

None.

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": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

<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

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

Что

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

Эта политика особенно полезна, если вы хотите преобразовать сообщения с помощью 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>

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

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

<Параметры>/<ОпуститьXmlДекларацию>

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

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<Параметры>/<ИмяБлокаПространстваИмен>
<Параметры>/<ИмяУзлаПространстваИменПоУмолчанию>
Элементы <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>

<Параметры>/<ИмяКорневогоЭлементаОбъекта>

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

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

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

И вы устанавливаете <ObjectRootElementName> как:

<ObjectRootElementName>Root</ObjectRootElementName>

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

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

<Параметры>/<ИмяАтрибутБлока>
Элементы <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>/<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>

<Параметры>/<Отступ>

Задаёт отступ для 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>

Если для значения Null не указано значение (или указано значение, отличное от 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 и итеративно добавлять элементы конфигурации по мере необходимости.

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

Схемы

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

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

None.

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": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

<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