Zasada JSONtoXML

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Co

Ta zasada konwertuje wiadomości z formatu JavaScript Object Notation (JSON) na język XML (Extensible Markup Language), dając Ci kilka opcji kontrolowania sposobu konwersji wiadomości.

Zasada jest szczególnie przydatna, jeśli chcesz przekształcać wiadomości za pomocą języka XSL. Po przekonwertowaniu ładunku JSON na XML użyj zasady XSL Transform z niestandardowym arkuszem stylów, aby przeprowadzić potrzebną transformację.

Zakładając, że celem jest przekonwertowanie żądania w formacie JSON na żądanie w formacie XML, zasada zostanie dołączona do przepływu żądania (np. Request / ProxyEndpoint / PostFlow).

Przykłady

Szczegółowe omówienie konwersji między formatami JSON i XML znajdziesz w artykule Problem z konwersją tablicy JSON na tablicę XML w obiekcie odpowiedzi.

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

Dokumentacja elementów

Poniżej znajdziesz elementy i atrybuty, które możesz skonfigurować w tej zasadzie.

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

Atrybuty <JSONToXML>

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Source>

Zmienna, żądanie lub odpowiedź, która zawiera komunikat JSON, który chcesz przekonwertować do XML.

Jeśli element <Source> nie jest zdefiniowany, jest traktowany jako komunikat (który jest rozpoznawany jako żądanie, gdy zasada jest dołączona do przepływu żądania, lub jako odpowiedź, gdy zasada jest dołączona do przepływu odpowiedzi).

Jeśli nie można rozpoznać zmiennej źródłowej lub jest ona rozpoznawana jako typ inny niż komunikat, zasada zgłasza błąd.

<Source>request</Source>

Element <OutputVariable>

Przechowuje wynik konwersji z formatu JSON na XML. Zwykle jest to ta sama wartość co źródło, czyli zwykle żądanie JSON jest konwertowane na żądanie XML.

Ładunek komunikatu JSON jest analizowany i konwertowany na XML, a nagłówek HTTP Content-type komunikatu w formacie XML jest ustawiany na text/xml;charset=UTF-8.

Jeśli element OutputVariable nie jest określony, source jest traktowany jako OutputVariable. Jeśli na przykład source to request, domyślna wartość OutputVariable to request.

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

Określa, czy przestrzeń nazw XML ma być pomijana w danych wyjściowych. Wartość domyślna to false co oznacza, że przestrzeń nazw jest uwzględniana w danych wyjściowych.

Na przykład to ustawienie konfiguruje zasadę tak, aby pomijała przestrzeń nazw:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

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

Format JSON nie obsługuje przestrzeni nazw, natomiast dokumenty XML często ich wymagają. NamespaceBlockName umożliwia zdefiniowanie właściwości JSON, która będzie służyć jako źródło definicji przestrzeni nazw w pliku XML wygenerowanym przez zasadę. (Oznacza to, że źródłowy plik JSON musi zawierać właściwość, którą można zmapować na przestrzeń nazw oczekiwaną przez aplikację, która korzysta z wynikowego pliku XML).

Na przykład te ustawienia:

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

wskazują, że w źródłowym pliku JSON istnieje właściwość o nazwie #namespaces, która zawiera co najmniej 1 przestrzeń nazw oznaczoną jako domyślną. Na przykład:

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

jest konwertowane na:

<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> określa nazwę elementu głównego podczas konwersji z formatu JSON, który nie ma nazwanego elementu głównego na format XML.

Jeśli na przykład plik JSON wygląda tak:

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

A Ty ustawisz <ObjectRootElementName> jako:

<ObjectRootElementName>Root</ObjectRootElementName>

Wynikowy plik XML będzie wyglądać tak:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elements

<AttributeBlockName> umożliwia określenie, kiedy elementy JSON są konwertowane na atrybuty XML (a nie na elementy XML).

Na przykład to ustawienie konwertuje właściwości w obiekcie o nazwie #attrs na atrybuty XML:

<AttributeBlockName>#attrs</AttributeBlockName>

Ten obiekt JSON:

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

jest konwertowany na tę strukturę XML:

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

<AttributePrefix> konwertuje właściwość zaczynającą się od określonego prefiksu na atrybuty XML. Jeśli prefiks atrybutu jest ustawiony na @, na przykład:

<AttributePrefix>@</AttributePrefix>

Konwertuje ten obiekt JSON:

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

 }
}

na tę strukturę XML:

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

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> element

Konwertuje tablicę JSON na listę elementów XML o określonych nazwach elementu nadrzędnego i podrzędnego.

Na przykład te ustawienia:

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

konwertują tę tablicę JSON:

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

na tę strukturę XML:

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

<Options>/<Indent>

Określa, czy dane wyjściowe XML mają być wcięte. Wartość domyślna to false , co oznacza, że wcięcia nie są stosowane.

Na przykład to ustawienie konfiguruje zasadę tak, aby wcięcia były stosowane w danych wyjściowych:

<Indent>true</Indent>

Jeśli dane wejściowe JSON mają postać:

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

Dane wyjściowe bez wcięć wyglądają tak:

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

Gdy wcięcia są włączone, dane wyjściowe wyglądają tak:

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

<Options>/<TextNodeName> element

Konwertuje właściwość JSON na węzeł tekstowy XML o określonej nazwie. Na przykład to ustawienie:

<TextNodeName>age</TextNodeName>

konwertuje ten plik JSON:

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

na tę strukturę XML:

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

Jeśli element TextNodeName nie jest określony, plik XML jest generowany przy użyciu domyślnego ustawienia węzła tekstowego:

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

<Options>/<NullValue> element

Wskazuje wartość null. Domyślnie wartość to NULL.

Na przykład to ustawienie:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

na ten element XML:

<person></person>

Jeśli dla wartości null nie określono żadnej wartości (lub określono wartość inną niż I_AM_NULL), ten sam ładunek jest konwertowany na:

<person>I_AM_NULL</person>

<Options>/<InvalidCharsReplacement> element

Aby ułatwić obsługę nieprawidłowego kodu XML, który może powodować problemy z analizatorem, to ustawienie zastępuje wszystkie elementy JSON, które generują nieprawidłowy kod XML, ciągiem znaków. Na przykład to ustawienie:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Konwertuje ten obiekt JSON

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

na tę strukturę XML:

<First_Name>John<First_Name>

Zastosowanie

W typowym scenariuszu mediacji zasada JSON to XML w przepływie żądania przychodzącego jest często łączona z zasadą XMLtoJSON w przepływie odpowiedzi wychodzącej. Dzięki takiemu połączeniu zasad można udostępnić interfejs API JSON dla usług, które natywnie obsługują tylko format XML.

Często przydatne jest zastosowanie domyślnej (pustej) zasady JSON to XML i stopniowe dodawanie elementów konfiguracji w razie potrzeby.

W scenariuszach, w których interfejsy API są używane przez różne aplikacje klienckie, które mogą wymagać formatu JSON lub XML, format odpowiedzi można ustawić dynamicznie, konfigurując zasady JSON to XML i XML to JSON tak, aby były wykonywane warunkowo. Implementację tego scenariusza znajdziesz w artykule Zmienne przepływu i warunki.

Schematy

Dokumentacja błędów

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>

Powiązane artykuły

• XML to JSON: XML to JSON policy
• Transformacja XSL: zasada XSL Transform