XMLtoJSON-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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 diese Kombination von Richtlinien Eine JSON API kann 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.

Beispiele

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

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<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, für den erkannte Nullwerte in der Quellnachricht Conversion durchgeführt haben. Der Standardwert ist null. Diese Option ist nur wirksam, wenn RecognizeNull „true“ 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 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

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

These errors can occur when you deploy a proxy containing this policy.

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

Example fault rule

<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