JSONtoXML-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Mit dieser Richtlinie werden Nachrichten aus dem JSON-Format (JavaScript Object Notation) in das erweiterbare XML-Format konvertiert. Sie haben dabei mehrere Möglichkeiten, die Konvertierung von Nachrichten zu steuern.

Diese Richtlinie ist insbesondere nützlich, wenn Sie Nachrichten mit XSL transformieren möchten. Nachdem Sie eine JSON-Nutzlast in XML konvertiert haben, verwenden Sie die XSL-Transformationsrichtlinie mit einem benutzerdefinierten Stylesheet, um die gewünschte Transformation durchzuführen.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Nicht alle Nutzer müssen Richtlinien- und Umgebungstypen kennen. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Wenn Sie also eine Anfrage im JSON-Format in eine XML-formatierte Anfrage konvertieren, wird die Richtlinie an einen Anfrageablauf angehängt (z. B. Request / ProxyEndpoint/PostFlow).

Beispiele

Ausführliche Informationen finden Sie unter Konvertieren zwischen XML und JSON mit Apigee: Was Sie wissen müssen.

Anfrage konvertieren

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

Diese Konfiguration verwendet eine JSON-formatierte Anfragenachricht als Quelle und erstellt eine XML-formatierte Nachricht, die in die request OutputVariable eingetragen wird. Apigee verwendet den Inhalt dieser Variable automatisch als Nachricht für den nächsten Verarbeitungsschritt.

Elementverweis

Die folgenden Elemente und Attribute können Sie für diese Richtlinie konfigurieren:

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

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut Beschreibung Standard Präsenz
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen

 falsch Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Veraltet

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>
Standardeinstellung

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Präsenz Optional
Typ String

<Source>-Element

Die Variable, Anfrage oder Antwort, die die JSON-Nachricht enthält, die Sie in XML konvertieren möchten.

Wenn <Source> nicht definiert ist, wird sie als Nachricht behandelt. Diese löst sich in eine Anfrage auf, wenn die Richtlinie an einen Anfragefluss angehängt ist, oder in eine Antwort, wenn die Richtlinie an einen Antwortablauf angehängt ist.

Wenn die Quellvariable nicht aufgelöst werden kann oder in einen Nicht-Nachrichtentyp aufgelöst wird, gibt die Richtlinie einen Fehler aus.

<Source>request</Source>
Standard Anfrage oder Antwort, je nachdem, wo die Richtlinie dem API-Proxy-Ablauf hinzugefügt wird
Präsenz Optional
Typ message

<OutputVariable>-Element

Speichert die Ausgabe der Konversion von JSON in das XML-Format. Dies ist in der Regel derselbe Wert wie die Quelle, d. h. normalerweise wird eine JSON-Anfrage in eine XML-Anfrage konvertiert.

Die Nutzlast der JSON-Nachricht wird geparst und in XML konvertiert. Der Header für den HTTP-Inhaltstyp der XML-formatierten Nachricht wird auf text/xml;charset=UTF-8 gesetzt.

Wenn OutputVariable nicht angegeben ist, wird source als OutputVariable behandelt. Beispiel: Wenn source request ist, dann wird OutputVariable standardmäßig auf request gesetzt.

<OutputVariable>request</OutputVariable>
Standard Anfrage oder Antwort, je nachdem, wo die Richtlinie dem API-Proxy-Ablauf hinzugefügt wird
Präsenz Das Element ist obligatorisch, wenn die im <Source>-Element definierte Variable vom Typ „String“ ist.
Typ message

<Options>/<OmitXmlDeclaration>

Gibt an, dass die XML-Deklarationszeile aus der Ausgabe weggelassen wird. Eine XML-Deklarationszeile kann optional oben in einem XML-Dokument angezeigt werden. Ein typisches Beispiel sieht so aus: 

<?xml version="1.0" encoding="UTF-8"?>

In einigen Fällen muss eine solche Zeile in die Ausgabe dieser Richtlinie vermieden werden. Ein gutes Beispiel ist, wenn Sie planen, die Ausgabe dieser Richtlinie als Fragment in ein größeres XML-Dokument einzubetten. Da die Deklaration nur einmal in einem Dokument und nur oben im Dokument vorkommen sollte, ist es in diesem Fall wichtig, die XML-Deklarationszeile im XML-Fragment zu unterdrücken.

Der Standardwert für diese Option ist false. Das bedeutet, dass die Richtlinie die XML-Deklarationszeile in der Ausgabe enthält. Mit der folgenden Einstellung wird die Richtlinie so konfiguriert, dass die XML-Deklaration weggelassen wird:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Es gibt keine Möglichkeit, den Inhalt der XML-Deklarationszeile über die Konfiguration dieser Richtlinie zu gestalten oder zu beeinflussen. Die Richtlinie generiert immer UTF-8-codierten Text und verwendet immer die XML-Version 1.0. Wenn die Deklarationszeile enthalten ist, spiegelt sie dies entsprechend wider.

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>-Elemente

JSON unterstützt keine Namespaces, während XML-Dokumente diese häufig benötigen. Mit NamespaceBlockName können Sie ein JSON-Attribut definieren, das als Quelle einer Namespace-Definition in der durch die Richtlinie erstellten XML-Datei dient. (Die Quell-JSON muss also ein Attribut bereitstellen, das einem Namespace zugeordnet werden kann, der von der die resultierende XML aufnehmenden Anwendung erwartet wird.)

Zum Beispiel die folgenden Einstellungen:

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

Gibt an, dass das Attribut #namespaces in der JSON-Quelldatei vorhanden ist, in der mindestens ein Namespace als Standard ausgewiesen ist. Beispiel:

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

konvertiert zu:

<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> gibt bei der Konvertierung von JSON (in dem kein benanntes Root-Element existiert) zu XML den Namen des Root-Elements an.

Wenn die JSON-Datei beispielsweise so aussieht:

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

Und Sie <ObjectRootElementName> so festlegen:

<ObjectRootElementName>Root</ObjectRootElementName>

Dann wird die resultierende XML folgendermaßen aussehen:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix>-Elemente

Mit <AttributeBlockName> können Sie angeben, wann JSON-Elemente in XML-Attribute (und nicht in XML-Elemente) konvertiert werden.

Folgende Einstellung wandelt beispielsweise Attribute in einem Objekt namens #attrs in XML-Attribute um:

<AttributeBlockName>#attrs</AttributeBlockName>

Das folgende JSON-Objekt:

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

wird in folgende XML-Struktur konvertiert:

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

<AttributePrefix> konvertiert das Attribut, das mit dem angegebenen Präfix beginnt, in XML-Attribute. Wenn das Attributpräfix beispielsweise auf @ gesetzt ist:

<AttributePrefix>@</AttributePrefix>

Konvertiert das folgende JSON-Objekt:

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

 }
}

zu der folgenden XML-Struktur:

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

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

Wandelt ein JSON-Array in eine Liste von XML-Elementen mit angegebenen übergeordneten und untergeordneten Elementnamen um.

Zum Beispiel die folgenden Einstellungen:

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

konvertiert das folgende JSON-Array:

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

in die folgende XML-Struktur:

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

<Options>/<Indent>

Gibt an, dass die XML-Ausgabe eingerückt werden soll. Der Standardwert ist false, d. h. nicht einrücken.

Folgende Einstellung konfiguriert die Richtlinie zum Einrücken der Ausgabe:

<Indent>true</Indent>

Wenn die JSON-Eingabe folgendes Format hat:

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

Dann sieht die Ausgabe ohne Einrückung so aus:

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

Ist die Einrückung aktiviert, lautet die Ausgabe:

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

<Options>/<TextNodeName>-Element

Wandelt ein JSON-Attribut in einen XML-Textknoten mit dem angegebenen Namen um. Zum Beispiel die folgende Einstellung:

<TextNodeName>age</TextNodeName>

konvertiert diesen JSON-Code:

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

zu dieser XML-Struktur:

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

Wenn TextNodeName nicht angegeben ist, wird die XML unter Verwendung der Standardeinstellung für Textknoten generiert:

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

<Options>/<NullValue>-Element

Gibt einen Nullwert an. Der Standardwert ist NULL.

Zum Beispiel die folgende Einstellung:

<NullValue>I_AM_NULL</NullValue>
Konvertiert das folgende JSON-Objekt: 
{"person" : "I_AM_NULL"}

zum folgenden XML-Element:

<person></person>

Wenn für den Nullwert kein Wert (oder ein anderer Wert als I_AM_NULL) angegeben ist, wird die gleiche Nutzlast folgendermaßen konvertiert:

<person>I_AM_NULL</person>

<Options>/<InvalidCharsReplacement>-Element

Um ungültige XML zu vermeiden, die zu Problemen mit Parsern führen können, ersetzt diese Einstellung alle JSON-Elemente, die ungültige XML-Daten erzeugen, durch den String. Zum Beispiel die folgende Einstellung:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Konvertiert dieses JSON-Objekt

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

zu dieser XML-Struktur:

<First_Name>John<First_Name>

Verwendungshinweise

In einem typischen Vermittlungsszenario wird eine JSON-zu-XML-Richtlinie für den eingehenden Anfragefluss häufig mit einer XMLtoJSON-Richtlinie im ausgehenden Antwortfluss kombiniert. Durch die Kombination der Richtlinien kann eine JSON API für Dienste verfügbar gemacht werden, die nativ nur XML unterstützen.

Es ist oft sinnvoll, die leere Standard-JSON-XML-Richtlinie anzuwenden und die Konfigurationselemente nach Bedarf schrittweise hinzuzufügen.

In Szenarien, in denen APIs von verschiedenen Client-Apps genutzt werden, die entweder JSON und XML erfordern, kann das Format der Antwort dynamisch konfiguriert werden. Dazu konfigurieren Sie JSON-to-XML- und XML-to-JSON-Richtlinien für die bedingte Ausführung. Eine Implementierung dieses Szenarios finden Sie unter Ablaufvariablen und -bedingungen.

Schemas

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Behebung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache Beheben
steps.jsontoxml.ExecutionFailed 500 Die Nutzlast der JSON-Eingabe ist leer oder die an JSON-zu-XML-Richtlinie übergebene JSON-Eingabe ist ungültig oder fehlerhaft.
steps.jsontoxml.InCompatibleTypes 500 Dieser Fehler tritt auf, wenn der Typ der im <Source>-Element definierten Variable und das <OutputVariable>-Element nicht identisch sind. Der Typ der im Element <Source>-Element enthaltenen Variablen muss mit dem Typ der im <OutputVariable>Element enthaltenden Variable übereinstimmen. Gültige Typen sind message und string.
steps.jsontoxml.InvalidSourceType 500 Dieser Fehler tritt auf, wenn der Variablentyp, der zum Definieren des <Source>-Elements verwendet wird, ungültig ist. Die gültigen Variablentypen sind message und string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 Dieser Fehler tritt auf, wenn die im <Source>-Element der JSON-zu-XML-Richtlinie angegebene Variable den Typ "String" hat und das <OutputVariable>-Element nicht definiert ist. Das <OutputVariable>-Element ist obligatorisch, wenn die im <Source>-Element definierte Variable vom Typ "String" ist.
steps.jsontoxml.SourceUnavailable 500 Dieser Fehler tritt auf, wenn für die im <Source>-Element der JSON-zu-XML-Richtlinie angegebene Variable message eine der folgenden Aussagen gilt:
  • Außerhalb des Geltungsbereichs (nicht im spezifischen Ablauf verfügbar, in dem die Richtlinie ausgeführt wird) oder
  • kann nicht gelöst werden (ist nicht definiert)

Bereitstellungsfehler

–

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. jsontoxml.JSON-to-XML-1.failed = true

Beispiel für eine Fehlerantwort

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

Beispiel für eine Fehlerregel

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

Weitere Informationen