Zasada JSONtoXML

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

Ta zasada konwertuje wiadomości z formatu JSON na rozszerzalny język znaczników (XML), co daje kilka opcji kontrolowania sposobu konwersji wiadomości.

Zasada ta jest szczególnie przydatna, jeśli chcesz przekształcać wiadomości za pomocą 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 przekształcenie żą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>

Odwołanie do elementu

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

<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ź zawierające wiadomość JSON, którą chcesz przekonwertować na XML.

Jeśli parametr <Source> nie jest zdefiniowany, jest traktowany jako wiadomość (co w przypadku dołączenia zasady do przepływu żądania jest interpretowane jako żądanie, a w przypadku dołączenia zasady do przepływu odpowiedzi – jako odpowiedź).

Jeśli zmiennej źródłowej nie można rozpoznać lub ma ona typ inny niż typ wiadomości, 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 wiadomości JSON jest analizowany i konwertowany na XML, a nagłówek HTTP Content-type wiadomości w formacie XML jest ustawiany na text/xml;charset=UTF-8.

Jeśli nie określono właściwości OutputVariable, wartość source jest traktowana jako OutputVariable. Jeśli na przykład wartość source to request, domyślna wartość OutputVariable to request.

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

Określa, że przestrzeń nazw XML ma zostać pominięta w danych wyjściowych. Wartość domyślna to false, co oznacza, że przestrzeń nazw zostanie uwzględniona w danych wyjściowych.

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

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

Format JSON nie obsługuje przestrzeni nazw, a dokumenty XML często ich wymagają. NamespaceBlockName umożliwia zdefiniowanie właściwości JSON, która 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 mapować 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>

oznacza, ż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ślna. 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"
   }
}

przekształca się w:

<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 JSON wygląda tak:

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

Ustawiasz <ObjectRootElementName> jako:

<ObjectRootElementName>Root</ObjectRootElementName>

Wynikowy plik XML wygląda tak:

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

Elementy <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

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

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

<AttributeBlockName>#attrs</AttributeBlockName>

Ten obiekt JSON:

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

zostanie przekonwertowany na tę strukturę XML:

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

<AttributePrefix> przekształca usługę zaczynającą się od określonego prefiksu na atrybuty XML. Gdy prefiks atrybutu ma wartość @, na przykład:

<AttributePrefix>@</AttributePrefix>

Konwertuje ten obiekt JSON:

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

 }
}

do tej struktury XML:

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

Element <Options>/<ArrayRootElementName>
Element <Options>/<ArrayItemElementName>

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>

konwertuje tę tablicę JSON:

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

do tej struktury 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 brak wcięcia.

Na przykład to ustawienie konfiguruje zasadę w taki sposób, aby w danych wyjściowych stosować wcięcia:

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

Po włączeniu wcięcia dane wyjściowe wyglądają tak:

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

Element <Options>/<TextNodeName>

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

<TextNodeName>age</TextNodeName>

konwertuje ten kod JSON:

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

do tej struktury XML:

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

Jeśli nie podasz wartości TextNodeName, kod XML zostanie wygenerowany przy użyciu domyślnego ustawienia węzła tekstowego:

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

Element <Options>/<NullValue>

Oznacza wartość null. Domyślna wartość to NULL.

Na przykład to ustawienie:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

do tego elementu XML:

<person></person>

Jeśli dla wartości Null nie podano żadnej wartości (lub podano wartość inną niż I_AM_NULL), ten sam ładunek zostanie przekształcony w:

<person>I_AM_NULL</person>

Element <Options>/<InvalidCharsReplacement>

Aby ułatwić obsługę nieprawidłowego kodu XML, który może powodować problemy z parserem, 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"
}

do tej struktury XML:

<First_Name>John<First_Name>

Zastosowanie

W typowym scenariuszu mediacji zasady JSONtoXML w przypadku przepływu żądań przychodzących są często łączone z zasadami XMLtoJSON w przypadku przepływu odpowiedzi wychodzących. Dzięki połączeniu zasad w ten sposób można udostępnić interfejs JSON API usługom, które natywnie obsługują tylko XML.

Często przydatne jest zastosowanie domyślnej (pustej) zasady JSON do XML i iteracyjne dodawanie elementów konfiguracji w miarę potrzeb.

W scenariuszach, w których interfejsy API są używane przez różne aplikacje klienckie, które mogą wymagać formatów JSON i XML, format odpowiedzi można ustawiać dynamicznie, konfigurując zasady konwersji z JSON na XML i z XML na JSON, które będą wykonywane warunkowo. Przykład wdrożenia tego scenariusza znajdziesz w sekcji Zmienne i warunki przepływu.

Schematy

Odniesienie do błędu

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Brak.

Zmienne błędów

Te zmienne są ustawiane po wystąpieniu błędu działania. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

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

Przykładowa reguła błędu

<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 do JSON: zasady XML do JSON
• Przekształcenie XSL: zasada przekształcenia XSL