XMLtoJSON-Richtlinie

Sie lesen die Dokumentation zu Apigee X.
Apigee Edge-Dokumentation aufrufen

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 die Kombination der Richtlinien kann eine JSON API für Back-End-Dienste verfügbar gemacht 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.

Antwort konvertieren

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

Diese Konfiguration – die Minimalkonfiguration, die für die Konvertierung von XML in JSON erforderlich ist – verwendet eine XML-formatierte Antwort als Quelle und erstellt dann eine JSON-formatierte Nachricht, die in die response 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:

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

Attribut	Beschreibung	Standard	Presence
`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. Siehe auch: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	false	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	Verworfen

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

Standard

Standard	– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs `name` der Richtlinie verwendet.
Presence	Optional
Typ	String

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.

Presence Optional

Typ String

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

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

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>

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

Standard	false
Präsenz	Optional
Typ	Boolean

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

Standard	false
Präsenz	Optional
Typ	Boolean

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

Standard	false
Präsenz	Optional
Typ	Boolean

<Options>/<NullValue>-Element

Gibt an, was in der zu konvertierenden Nachricht einen Nullwert darstellt. Der Wert ist standardmäßig NULL.

<NullValue>NULL</NullValue>

Standard	`NULL`
Präsenz	Optional
Typ	String

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

Standard	Siehe Beispiele oben.
Präsenz	Optional Wenn Sie `<NamespaceBlockName>` angeben, müssen Sie auch die anderen beiden Elemente angeben.
Typ	Strings

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

Standard	`<TextAlwaysAsProperty>`: false `<TextNodeName>`: keine Angabe
Präsenz	Optional
Typ	`<TextAlwaysAsProperty>`: Boolean `<TextNodeName>`: String

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

Standard	Siehe Beispiele oben.
Präsenz	Optional
Typ	String

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

Standard	Siehe Beispiele oben.
Präsenz	Optional
Typ	String

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

Standard	0 (keine Ebenenentfernung)
Präsenz	Optional
Typ	Integer

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

Standard	–
Präsenz	Optional
Typ	String

Attribute

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

Attribut Beschreibung Präsenz Typ

entpacken

Attribut	Beschreibung	Präsenz	Typ
entpacken	Standardwert: false Das Element wird aus der JSON-Ausgabe entfernt. Verwenden Sie diese Option, um die JSON-Datei zu optimieren oder zu „verpacken“ und damit den JSON-Pfad zu reduzieren, der zum Abrufen von Werten erforderlich ist. Beispielsweise können Sie anstelle von `$.teachers.teacher.studentnames.name[]` den JSON-Code vereinfachen und `$.teachers.studentnames[]` verwenden. Hier ein JSON-Beispiel: { "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]}... In diesem Beispiel könnten Sie vermuten, dass die Elemente `teacher` und die `name`-Elemente der Studentnamen unnötig sind. Sie können sie also entfernen oder entpacken. In diesem Fall konfigurieren Sie das Element `<Path>` folgendermaßen: <TreatAsArray> <Path unwrap="true">teachers/teacher</Path> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> Das Attribut `unwrap` ist auf „true“ gesetzt und die Pfade zu den Elementen, die entpackt werden sollen, werden bereitgestellt. Die JSON-Ausgabe sieht jetzt so aus: { "teachers" : [{ "name" : "teacherA", "studentnames" : ["student1","student2"] }]... Da sich das Element `<Path>` im Element `<TreatAsArray>` befindet, werden beide Elemente im Pfad als Arrays in der JSON-Ausgabe behandelt.	Optional	Boolean

Standardwert: false

Das Element wird aus der JSON-Ausgabe entfernt. Verwenden Sie diese Option, um die JSON-Datei zu optimieren oder zu „verpacken“ und damit den JSON-Pfad zu reduzieren, der zum Abrufen von Werten erforderlich ist. Beispielsweise können Sie anstelle von $.teachers.teacher.studentnames.name[*] den JSON-Code vereinfachen und $.teachers.studentnames[*] verwenden.

Hier ein JSON-Beispiel:


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

In diesem Beispiel könnten Sie vermuten, dass die Elemente teacher und die name-Elemente der Studentnamen unnötig sind. Sie können sie also entfernen oder entpacken. In diesem Fall konfigurieren Sie das Element <Path> folgendermaßen:


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

Das Attribut unwrap ist auf „true“ gesetzt und die Pfade zu den Elementen, die entpackt werden sollen, werden bereitgestellt. Die JSON-Ausgabe sieht jetzt so aus:


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

Da sich das Element <Path> im Element <TreatAsArray> befindet, werden beide Elemente im Pfad als Arrays in der JSON-Ausgabe behandelt.

Optional

Boolean

Weitere Beispiele und eine Schritt-für-Schritt-Anleitung finden Sie in diesem Artikel der Apigee-Community: 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>

Standard	Geben Sie den Namen eines verfügbaren Formats ein: `xml.com`, `yahoo`, `google`, `badgerFish`
Präsenz	Ist erforderlich, wenn `<Options>` nicht verwendet wird.
Typ	String

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

Fehlercode	HTTP-Status	Ursache
`steps.xmltojson.ExecutionFailed`	`ExecutionFailed`	Dieser Fehler tritt auf, wenn die Eingabenutzlast (XML) leer ist oder die Eingabe-XML ungültig oder fehlerhaft ist.
`steps.xmltojson.InCompatibleTypes`	`ExecutionFailed`	Dieser Fehler tritt auf, wenn der Typ der im Element `<Source>` definierten Variable und das Element `<OutputVariable>` nicht identisch sind. Der Typ der im Element `<Source>` enthaltenen Variablen muss mit dem Typ der im Element `<OutputVariable>` enthaltenden Variable übereinstimmen.
`steps.xmltojson.InvalidSourceType`	`ExecutionFailed`	Dieser Fehler tritt auf, wenn der Typ der Variablen zum Definieren des Elements `<Source>` ungültig ist. Gültige Variablentypen sind "message" und "string".
`steps.xmltojson.OutputVariableIsNotAvailable`	`ExecutionFailed`	Dieser Fehler tritt auf, wenn die im `<Source>`-Element der XML-zu-JSON-Richtlinie angegebene Variable den Typ "String" aufweist und das Element `<OutputVariable>` nicht definiert ist. Das Element `<OutputVariable>` ist obligatorisch, wenn die im Element `<Source>` definierte Variable vom Typ "String" ist.
`steps.xmltojson.SourceUnavailable`	`ExecutionFailed`	Dieser Fehler tritt auf, wenn die im Element `<Source>` der XML-zu-JSON-Richtlinie angegebene Variable message entweder: 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

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername	Ursache	Diverse Fehlerkorrekturen
`EitherOptionOrFormat`	Ist eines der Elemente `<Options>` oder `<Format>` in der "XML-to-JSON"-Richtlinie nicht deklariert, schlägt die Bereitstellung des API-Proxys fehl.
`UnknownFormat`	Wenn für das Element `<Format>` in der "XML-to-JSON"-Richtlinie ein unbekanntes Format definiert ist, schlägt die Bereitstellung des API-Proxys fehl. Vordefinierte Formate sind: `xml.com`, `yahoo`, `google` und `badgerFish`.

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 = "SourceUnavailable"`
`xmltojson.policy_name.failed`	`policy_name` ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	`xmltojson.XMLtoJSON-1.failed = true`

Beispiel für eine Fehlerantwort

Hinweis: Bei der Fehlerbehandlung besteht die Best Practice darin, den Teil errorcode der Fehlerantwort zu beachten. Verlassen Sie sich nicht auf den Text in faultstring. Er kann sich ändern.

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

XMLtoJSON-Richtlinie

Was

Info

Beispiele

Antwort konvertieren

Elementverweis

<XMLtoJSON>-Attribute

<DisplayName>-Element

<Source>-Element

<OutputVariable>-Element

<Options>

<Options>/<RecognizeNumber>-Element

<Options>/<RecognizeBoolean>-Element

<Options>/<RecognizeNull>-Element

<Options>/<NullValue>-Element

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

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

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

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

<Options>/<StripLevels>-Element

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

Attribute

<Format>

xml.com

yahoo

google

badgerFish

Schemas

Fehlerreferenz

Laufzeitfehler

Bereitstellungsfehler

Fehlervariablen

Beispiel für eine Fehlerantwort

Beispiel für eine Fehlerregel

Weitere Informationen

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

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

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

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