JSONtoXML-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

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.

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

Samples

Ausführliche Informationen zum Konvertieren von JSON und XML finden Sie unter 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>

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:

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

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

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

<Options>/<OmitXmlDeclaration>

Gibt an, dass der XML-Namespace aus der Ausgabe ausgelassen wird. Der Standardwert ist false. Das bedeutet, dass der Namespace in der Ausgabe enthalten ist.

Folgende Einstellung konfiguriert die Richtlinie beispielsweise so, dass der Namespace weggelassen wird:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

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

{"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 Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung 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.

Bereitstellungsfehler

–

Fehlervariablen

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

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

• XML zu JSON: XML-zu-JSON-Richtlinie
• XSL-Transformation: XSL-Transformationsrichtlinie