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

Что
Эта политика преобразует сообщения из формата нотации объектов JavaScript (JSON) в расширяемый язык разметки (XML), предоставляя вам несколько вариантов управления преобразованием сообщений.
Эта политика особенно полезна, если вы хотите преобразовать сообщения с помощью XSL. После преобразования полезных данных JSON в XML используйте политику преобразования XSL с настраиваемой таблицей стилей, чтобы выполнить необходимое преобразование.
Предполагая, что целью является преобразование запроса в формате JSON в запрос в формате XML, политика будет прикреплена к потоку запроса (например, Request/ProxyEndpoint/PostFlow).
Образцы
Подробное обсуждение преобразования JSON и XML см. в http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html .
Преобразование запроса
<JSONToXML name="jsontoxml"> <Source>request</Source> <OutputVariable>request</OutputVariable> </JSONToXML>
Эта конфигурация принимает сообщение запроса в формате JSON в качестве источника, а затем создает сообщение в формате XML, которое заполняется в OutputVariable request
. Edge автоматически использует содержимое этой переменной в качестве сообщения для следующего шага обработки.
Ссылка на элемент
Ниже приведены элементы и атрибуты, которые вы можете настроить в этой политике.
<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>
В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:
Атрибут | Описание | По умолчанию | Присутствие |
---|---|---|---|
name | Внутреннее имя политики. Значение атрибута При необходимости используйте элемент | Н/Д | Необходимый |
continueOnError | Установите значение Установите значение | ЛОЖЬ | Необязательный |
enabled | Установите значение Установите значение | истинный | Необязательный |
async | Этот атрибут устарел. | ЛОЖЬ | Устарело |
Элемент <DisplayName>
Используйте в дополнение к атрибуту name
, чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.
<DisplayName>Policy Display Name</DisplayName>
По умолчанию | Н/Д Если вы опустите этот элемент, будет использовано значение атрибута |
---|---|
Присутствие | Необязательный |
Тип | Нить |
Элемент <Источник>
Переменная, запрос или ответ, содержащая сообщение JSON, которое вы хотите преобразовать в XML.
Если <Source>
не определен, то он рассматривается как сообщение (которое разрешается как запрос, когда политика прикреплена к потоку запросов, или как ответ, когда политика прикреплена к потоку ответов).
Если исходную переменную невозможно разрешить или она преобразуется в тип, не являющийся сообщением, политика выдает ошибку.
<Source>request</Source>
По умолчанию | запрос или ответ, в зависимости от того, где политика добавляется в поток прокси-сервера API. |
Присутствие | Необязательный |
Тип | сообщение |
Элемент <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>
По умолчанию | запрос или ответ, в зависимости от того, где политика добавляется в поток прокси-сервера API. |
Присутствие | Этот элемент является обязательным, если переменная, определенная в элементе <Source> , имеет строковый тип. |
Тип | сообщение |
<Параметры>/<ОбъявлениеOmitXml>
Указывает, что пространство имен 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>
<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>
<Параметры>/<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>
<Параметры>/<Отступ>
Указывает отступ для вывода 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 to XML в потоке входящих запросов часто сочетается с политикой XMLtoJSON в потоке исходящих ответов. Комбинируя политики таким образом, API JSON можно предоставить службам, которые изначально поддерживают только 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.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
steps.jsontoxml.ExecutionFailed |
500 | The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed. | build |
steps.jsontoxml.InCompatibleTypes |
500 | This error occurs if the type of the variable defined in the <Source> element and
the <OutputVariable> element are not the same. It is mandatory that the type of the
variables contained within the <Source> element and the <OutputVariable> element
matches. The valid types are message and string . |
build |
steps.jsontoxml.InvalidSourceType |
500 | This error occurs if the type of the variable used to define the <Source> element
is invalid. The valid types of variable are message and string . |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 | This error occurs if the variable specified in the <Source> element of the JSON to
XML Policy is of type string and the <OutputVariable> element is not defined.
The <OutputVariable> element is mandatory when the variable defined in the <Source>
element is of type string. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
This error occurs if the message
variable specified in the <Source> element of the JSON to XML policy is either:
|
build |
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.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "SourceUnavailable" |
jsontoxml.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | jsontoxml.JSON-to-XML-1.failed = true |
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