XMLtoJSON-Richtlinie

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

Was

Diese Richtlinie konvertiert Nachrichten aus dem erweiterbaren Markup Language-Format (XML) in die JavaScript Object Notation (JSON). Dadurch haben Sie mehrere Möglichkeiten, die Konvertierung von Nachrichten zu steuern.

Angenommen, der Intent ist die Konvertierung einer XML-formatierten Antwort in eine JSON-formatierte Antwort. In diesem Fall wird die Richtlinie an einen Antwortablauf angehängt (z. B. Response / ProxyEndpoint / PostFlow).

Info

In einem typischen Vermittlungsszenario wird eine JSON-zu-XML-Richtlinie für den eingehenden Anfragefluss häufig mit einer XML-zu-JSON-Richtlinie im ausgehenden Antwortfluss kombiniert. Durch das Kombinieren von Richtlinien kann eine JSON API für Back-End-Dienste bereitgestellt werden, die nativ nur XML unterstützen.

In Szenarien, in denen APIs von verschiedenen Client-Anwendungen genutzt werden, die JSON oder XML erfordern, kann das Antwortformat dynamisch festgelegt werden. Dazu konfigurieren Sie die Ausführungen der JSON-zu-XML- und XML-zu-JSON-Richtlinien nach Bedingungen. Eine Implementierung dieses Szenarios finden Sie unter Ablaufvariablen und -bedingungen.

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.

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Elementverweis

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

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</DisplayName>
    <Source>response</Source>
    <OutputVariable>response</OutputVariable>
    <Options>
        <RecognizeNumber>true</RecognizeNumber>
        <RecognizeBoolean>true</RecognizeBoolean>
        <RecognizeNull>true</RecognizeNull>
        <NullValue>NULL</NullValue>
        <NamespaceBlockName>#namespaces</NamespaceBlockName>
        <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
        <NamespaceSeparator>***</NamespaceSeparator>
        <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
        <TextNodeName>TEXT</TextNodeName>
        <AttributeBlockName>FOO_BLOCK</AttributeBlockName>
        <AttributePrefix>BAR_</AttributePrefix>
        <OutputPrefix>PREFIX_</OutputPrefix>
        <OutputSuffix>_SUFFIX</OutputSuffix>
        <StripLevels>2</StripLevels>
        <TreatAsArray>
            <Path unwrap="true">teachers/teacher/studentnames/name</Path>
        </TreatAsArray>
    </Options>
    <!-- Use Options or Format, not both -->
    <Format>yahoo</Format>
</XMLToJSON>

<XMLtoJSON>-Attribute

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1"> 

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 XML-Nachricht enthält, die in das JSON-Format konvertiert werden soll.

Der HTTP-Inhaltstyp-Header der Quellnachricht muss auf application/xml gesetzt sein, andernfalls wird die Richtlinie nicht erzwungen.

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>response</Source>

<OutputVariable>-Element

Speichert die Ausgabe der XML-zu-JSON-Formatkonvertierung. Dies ist in der Regel der gleiche Wert wie die Quelle, d. h. die XML-Antwort wird normalerweise in eine JSON-Antwort konvertiert.

Die Nutzlast der XML-Nachricht wird geparst und in JSON konvertiert. Der HTTP-Inhaltsheader der XML-formatierten Nachricht wird auf application/json gesetzt.

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

<OutputVariable>response</OutputVariable>

<Options>

Mit Optionen können Sie die XML-zu-JSON-Umwandlung steuern. Verwenden Sie entweder die Gruppe <Options>, mit der Sie bestimmte Konvertierungseinstellungen hinzufügen können, oder verwenden Sie das Element <Format>, mit dem Sie eine Vorlage mit vordefinierten Optionen referenzieren können. Sie können nicht sowohl <Options> als auch <Format> verwenden.

<Options> ist erforderlich, wenn <Format> nicht verwendet wird.

<Options>/<RecognizeNumber>-Element

Bei „true“ behalten Zahlenfelder in der XML-Nutzlast ihr ursprüngliches Format bei.

<RecognizeNumber>true</RecognizeNumber>

Betrachten Sie folgendes XML-Beispiel:

<a>
  <b>100</b>
  <c>value</c>
</a>

Konvertiert bei true zu:

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

Konvertiert bei false zu:

{
    "a": {
        "b": "100",
        "c": "value"
    }
}

<Options>/<RecognizeBoolean>-Element

Erlaubt es der Konvertierung, boolesche Richtig/Falsch-Werte beizubehalten, anstatt die Werte in Strings umzuwandeln.

<RecognizeBoolean>true</RecognizeBoolean>

Für das folgende XML-Beispiel gilt:

<a>
  <b>true</b>
  <c>value</c>
</a>

Konvertiert bei true zu:

{
    "a": {
        "b": true,
        "c": "value"
    }
}

Konvertiert bei false zu:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

<Options>/<RecognizeNull>-Element

Hiermit können leere Werte in Nullwerte konvertiert werden.

<RecognizeNull>true</RecognizeNull>

Für die folgende XML-Datei:

<a>
  <b></b>
  <c>value</c>
</a>

Konvertiert bei true zu:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

Konvertiert bei false zu:

{
  "a": {
    "b": {},
    "c": "value"
  }
}

<Options>/<NullValue>-Element

Gibt den Wert an, in den erkannte Nullwerte in der Quellnachricht konvertiert werden sollen. Der Standardwert ist null. Diese Option wird nur angewendet, wenn RecognizeNull wahr ist.

<NullValue>not-present</NullValue>

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

Verwenden Sie diese Elemente zusammen.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
<NamespaceSeparator>***</NamespaceSeparator>

Betrachten Sie folgendes XML-Beispiel:

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">
  <ns1:b>value</ns1:b>
</a>

Ist NamespaceSeparator nicht angegeben, so wird die folgende JSON-Struktur generiert:

{
    "a": {
        "b": "value"
    }
}

Wenn die Elemente NamespaceBlockName, DefaultNamespaceNodeName und NamespaceSeparator als #namespaces, & bzw. *** angegeben werden, wird die folgende JSON-Struktur generiert:

{
    "a": {
        "#namespaces": {
            "&": "http://ns.com",
            "ns1": "http://ns1.com"
        },
        "ns1***b": "value"
    }
}

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>-Elemente

Verwenden Sie diese Elemente zusammen.

Bei der Einstellung true wird der Inhalt des XML-Elements in ein String-Attribut konvertiert.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

Für die folgende XML-Datei:

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

Wenn TextAlwaysAsProperty auf true und TextNodeName auf TEXT festgelegt ist, wird folgende JSON-Struktur generiert:

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

Wenn TextAlwaysAsProperty auf false und TextNodeName auf TEXT festgelegt ist, wird folgende JSON-Struktur generiert:

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}

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

Verwenden Sie diese Elemente zusammen.

Sie können Werte in einem JSON-Block gruppieren und Präfixe an die Attributnamen anhängen.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName>
<AttributePrefix>BAR_</AttributePrefix>

Betrachten Sie folgendes XML-Beispiel:

<a attrib1="value1" attrib2="value2"/>

Wenn beide Attribute (AttributeBlockName als auch AttributePrefix) so angegeben werden, wie im Beispiel XML zu JSON definiert, wird die folgende JSON-Struktur generiert:

{
  "a": {
    "FOO_BLOCK": {
      "BAR_attrib1": "value1",
      "BAR_attrib2": "value2"
    }
  }
}

Wenn nur AttributeBlockName angegeben ist, wird folgende JSON-Struktur generiert:

{
    "a": {
        "FOO_BLOCK": {
            "attrib1": "value1",
            "attrib2": "value2"
        }
    }
}

Wenn nur AttributePrefix angegeben ist, wird folgende JSON-Struktur generiert:

{
    "a": {
        "BAR_attrib1": "value1",
        "BAR_attrib2": "value2"
    }
}

Ist keines von beiden angegeben, so wird folgende JSON-Struktur generiert:

{
    "a": {
        "attrib1": "value1",
        "attrib2": "value2"
    }
}

<Options>/<OutputPrefix>
<Options>/<OutputSuffix>-Elemente

Verwenden Sie diese Elemente zusammen.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

Betrachten Sie folgendes XML-Beispiel:

<a>value</a>

Wenn beide Attribute (OutputPrefix als auch OutputSuffix) so angegeben werden, wie im Beispiel XML zu JSON definiert, wird die folgende JSON-Struktur generiert:

PREFIX_{
    "a": "value"
}_SUFFIX

Ist nur OutputPrefix angegeben, so wird folgende JSON-Struktur generiert:

PREFIX_{
  "a" : "value"
}

Ist nur OutputSuffix angegeben, so wird folgende JSON-Struktur generiert:

{
  "a" : "value"
}_SUFFIX

Sind weder OutputPrefix noch OutputSuffix angegeben, so wird folgende JSON-Struktur generiert:

{
    "a": "value"
}

<Options>/<StripLevels>-Element

<Options>
    <StripLevels>4</StripLevels>
</Options>

Manchmal haben XML-Nutzlasten (z. B. SOAP) viele übergeordnete Ebenen, die Sie nicht in das konvertierte JSON-Format aufnehmen möchten. Im Folgenden sehen Sie eine Beispiel-SOAP-Antwort mit vielen Ebenen:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
          <GetCityWeatherByZIPResult>
              <State>CO</State>
              <City>Denver</City>
              <Description>Sunny</Description>
              <Temperature>62</Temperature>
          </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
  </soap:Body>
</soap:Envelope>

Es gibt vier Stufen, bevor du zum Bundesland, zum Ort, zur Beschreibung und zum Temperaturbereich gelangst. Ohne <StripLevels> würde die konvertierte JSON-Antwort so aussehen:

{
   "Envelope" : {
      "Body" : {
         "GetCityWeatherByZIPResponse" : {
            "GetCityWeatherByZIPResult" : {
               "State" : "CO",
               "City" : "Denver",
               "Description" : "Sunny",
               "Temperature" : "62"
            }
         }
      }
   }
}

Um diese ersten vier Ebenen aus der JSON-Antwort zu entfernen, legen Sie <StripLevels>4</StripLevels> fest. Das Ergebnis würde folgende JSON-Datei zur Verfügung stellen:

{
  "State" : "CO",
  "City" : "Denver",
  "Description" : "Sunny",
  "Temperature" : "62"
}

Sie können Ebenen bis zum ersten Element entfernen, das mehrere untergeordnete Elemente enthält. Was bedeutet das? Sehen wir uns ein komplexeres JSON-Beispiel an:

{
   "Envelope" : {
      "Body" : {
         "GetCityForecastByZIPResponse" : {
            "GetCityForecastByZIPResult" : {
               "ResponseText" : "City Found",
               "ForecastResult" : {
                  "Forecast" : [
                     {
                        "ProbabilityOfPrecipiation" : {
                           "Nighttime" : "00",
                           "Daytime" : 10
                        }  ...

Ebene 3 ist in diesem Beispiel GetCityForecastByZIPResponse, das nur ein untergeordnetes Element hat. Wenn Sie also <StripLevels>3</StripLevels> verwenden (die ersten drei Ebenen entfernen), würde die JSON-Datei so aussehen:

{
   "GetCityForecastByZIPResult" : {
      "ResponseText" : "City Found",
      "ForecastResult" : {
         "Forecast" : [
            {
               "ProbabilityOfPrecipiation" : {
                  "Nighttime" : "00",
                  "Daytime" : 10
               }  ...

Beachten Sie, dass GetCityForecastByZIPResult mehrere untergeordnete Elemente hat. Da dies das erste Element mit mehreren untergeordneten Elementen ist, können Sie diese letzte Ebene mithilfe von <StripLevels>4</StripLevels> entfernen. Dadurch erhalten Sie die folgende JSON:

{
   "ResponseText" : "City Found",
   "ForecastResult" : {
      "Forecast" : [
         {
            "ProbabilityOfPrecipiation" : {
               "Nighttime" : "00",
               "Daytime" : 10
            }  ...

Da Ebene 4 die erste Ebene ist, die mehrere untergeordnete Elemente enthält, können Sie keine tieferliegende Ebenen entfernen. Wenn Sie die Ebenen 5, 6, 7 zu entfernen versuchen, erhalten Sie weiterhin obige Antwort.

<Options>/<TreatAsArray>/<Path>-Element

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

Mit dieser Elementkombination können Sie dafür sorgen, dass Werte aus einem XML-Dokument in einem JSON-Array eingefügt werden. Dies ist beispielsweise hilfreich, wenn die Anzahl der untergeordneten Elemente variieren kann (von ein bis mehrere) und Sie möchten, dass die Werte immer in einem Array enthalten sind. Auf diese Weise bleibt Ihr Code stabil, da Sie jedes Mal Daten aus dem Array auf die gleiche Weise abrufen können. Beispiel: $.teachers.teacher.studentnames[0] ruft den ersten Studentennamen im Array ab, unabhängig von der Anzahl der Werte im Array.

Wir sehen uns noch einmal das Standardverhalten von XML-zu-JSON an und untersuchen, wie Sie die Ausgabe mit <TreatAsArray>/<Path> steuern.

Wenn ein XML-Dokument ein Element mit mehreren untergeordneten Werten enthält (in der Regel basierend auf einem Schema dessen Element maxOccurs='unbounded' ist), werden diese Werte durch die Richtlinie „XML-zu-JSON“ automatisch in ein Array eingefügt. Beispiel: Der folgende XML-Block

<teacher>
    <name>teacherA</name>
    <studentnames>
        <name>student1</name>
        <name>student2</name>
    </studentnames>
</teacher>

...wird automatisch in die folgende JSON-Datei ohne spezielle Richtlinienkonfiguration konvertiert:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}
           }
      }
}

Beachten Sie, dass die beiden Namen der Kursteilnehmer in ein Array eingefügt werden.

Ist jedoch nur ein Schüler im XML-Dokument vorhanden, so wird dieser Wert in der Richtlinie „XML-zu-JSON“ automatisch als einzelner String und nicht als String-Array behandelt, wie im folgenden Beispiel gezeigt:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : "student1"
              }
          }
      }
}

In den vorherigen Beispielen wurden ähnliche Daten einmal als Array, einmal als ein einzelner String konvertiert. Hier können Sie die Ausgabe mit dem Element <TreatAsArray>/<Path> steuern. Sie können beispielsweise dafür sorgen, dass die Namen der Schüler immer in ein Array gestellt werden, auch wenn es nur einen Wert gibt. Konfigurieren Sie dazu den Pfad zu dem Element, dessen Werte Sie in ein Array einfügen möchten. Beispiel:

<Options>
    <TreatAsArray>
        <Path>teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

Die Konfiguration oben würde den JSON-Code so schreiben:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : ["student1"]
              }
            ]
          }
      }
}

Beachten Sie, dass „Student1“ jetzt in einem Array enthalten ist. Unabhängig davon, ob es sich um einen oder mehrere Studenten handelt, können Sie diese in Ihrem Code mit folgendem JSONPath-Wert abrufen: $.teachers.teacher.studentnames.name[0]

Das <Path>-Element verfügt außerdem über ein unwrap-Attribut, das im nächsten Abschnitt erläutert wird.

Attribute

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

Weitere Beispiele und eine Schritt-für-Schritt-Anleitung zu Funktionen finden Sie in diesem Apigee Community-Artikel: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html.

<Format>

Mit dem Format können Sie die Umwandlung von XML in JSON steuern. Geben Sie den Namen einer vordefinierten Vorlage ein, die eine bestimmte Kombination der in diesem Thema beschriebenen Optionen enthält. Vordefinierte Formate sind xml.com, yahoo, google und badgerFish.

Verwenden Sie entweder das <Format>-Element oder die <Options>-Gruppe. Sie können nicht sowohl <Format> als auch <Options> verwenden.

Im Folgenden finden Sie die Formatdefinitionen der einzelnen vordefinierten Vorlagen.

xml.com

<RecognizeNull>true</RecognizeNull>
<TextNodeName>#text</TextNodeName>
<AttributePrefix>@</AttributePrefix>

yahoo

<RecognizeNumber>true</RecognizeNumber>
<TextNodeName>content</TextNodeName>

google

<TextNodeName>$t</TextNodeName>
<NamespaceSeparator>$</NamespaceSeparator>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>

badgerFish

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

Element-Syntax:

<Format>yahoo</Format>

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

Diese Fehler können auftreten, wenn Sie einen Proxy bereitstellen, der diese Richtlinie enthält.

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": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Beispiel für eine Fehlerregel

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

Weitere Informationen

JSON zu XML: JSON-zu-XML-Richtlinie