Zasada XMLtoJSON

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

Ta zasada konwertuje wiadomości z formatu XML na format JSON, co daje kilka opcji kontrolowania sposobu konwersji wiadomości.

Zakładając, że celem jest przekształcenie odpowiedzi w formacie XML na odpowiedź w formacie JSON, zasada zostanie dołączona do przepływu odpowiedzi (np. Odpowiedź / ProxyEndpoint / PostFlow).

Informacje

W typowym scenariuszu mediacji zasady JSON do XML w przepływie żądań przychodzących są często łączone z zasadami XML do JSON w przepływie odpowiedzi wychodzących. Dzięki połączeniu zasad w ten sposób można udostępnić interfejs API JSON dla usług backendu, które natywnie obsługują tylko format XML.

W scenariuszach, w których interfejsy API są używane przez różne aplikacje klienckie, które mogą wymagać formatu JSON lub XML, format odpowiedzi można ustawiać dynamicznie, konfigurując zasady konwersji z JSON na XML i z XML na JSON, aby były wykonywane warunkowo. Przykład wdrożenia tego scenariusza znajdziesz w sekcji Zmienne i warunki przepływu.

Przykłady

Szczegółowe omówienie konwersji między formatami JSON i XML znajdziesz w artykule Converting between XML and JSON with Apigee: What you need to know (Konwersja między formatami XML i JSON w Apigee: co musisz wiedzieć).

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

Odwołanie do elementu

Poniżej znajdziesz elementy i atrybuty, które możesz skonfigurować w tych zasadach.

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

Atrybuty <XMLtoJSON>

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

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Source>

Zmienna, żądanie lub odpowiedź zawierające wiadomość XML, którą chcesz przekonwertować na JSON.

Nagłówek Content-type HTTP wiadomości źródłowej musi mieć wartość application/xml, w przeciwnym razie zasada nie jest egzekwowana.

Jeśli parametr <Source> nie jest zdefiniowany, jest traktowany jako wiadomość (co w przypadku dołączenia zasady do przepływu żądania jest interpretowane jako żądanie, a w przypadku dołączenia zasady do przepływu odpowiedzi – jako odpowiedź).

Jeśli zmiennej źródłowej nie można rozpoznać lub ma ona typ inny niż typ wiadomości, zasada zgłasza błąd.

<Source>response</Source>

Element <OutputVariable>

Przechowuje dane wyjściowe konwersji z formatu XML na JSON. Zwykle jest to ta sama wartość co źródło, czyli zwykle odpowiedź XML jest konwertowana na odpowiedź JSON.

Ładunek wiadomości XML jest analizowany i konwertowany na format JSON, a nagłówek HTTP Content-type wiadomości w formacie XML jest ustawiany na application/json.

Jeśli nie określono właściwości OutputVariable, wartość source jest traktowana jako OutputVariable. Jeśli na przykład wartość source to response, domyślna wartość OutputVariable to response.

<OutputVariable>response</OutputVariable>

<Opcje>

Opcje umożliwiają kontrolowanie konwersji z XML na JSON. Użyj grupy <Options>, która umożliwia dodawanie konkretnych ustawień konwersji, lub elementu <Format>, który umożliwia odwoływanie się do szablonu wstępnie zdefiniowanych opcji. Nie możesz używać jednocześnie <Options> i <Format>.

Właściwość <Options> jest wymagana, jeśli nie używasz właściwości <Format>.

Element <Options>/<RecognizeNumber>

Jeśli wartość to „true”, pola liczbowe w ładunku XML zachowują oryginalny format.

<RecognizeNumber>true</RecognizeNumber>

Przyjrzyj się temu przykładowi XML:

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

Jeśli true, konwertuje na:

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

Jeśli false, konwertuje na:

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

Element <Options>/<RecognizeBoolean>

Umożliwia zachowanie wartości logicznych true/false w konwersji zamiast przekształcania ich w ciągi znaków.

<RecognizeBoolean>true</RecognizeBoolean>

W przypadku tego przykładu XML:

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

Jeśli true, konwertuje na:

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

Jeśli false, konwertuje na:

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

Element <Options>/<RecognizeNull>

Umożliwia konwertowanie pustych wartości na wartości null.

<RecognizeNull>true</RecognizeNull>

W przypadku tego kodu XML:

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

Jeśli true, konwertuje na:

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

Jeśli false, konwertuje na:

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

Element <Options>/<NullValue>

Wskazuje wartość, na którą należy przekonwertować rozpoznane wartości null w wiadomości źródłowej. Domyślna wartość to null. Ta opcja działa tylko wtedy, gdy RecognizeNull ma wartość Prawda.

<NullValue>not-present</NullValue>

Elementy <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

Używaj tych elementów razem.

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

Przyjrzyj się temu przykładowi XML:

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

Jeśli nie podasz wartości NamespaceSeparator, zostanie wygenerowana ta struktura JSON:

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

Jeśli elementy NamespaceBlockName, DefaultNamespaceNodeName i NamespaceSeparator są określone odpowiednio jako #namespaces, & i ***, generowana jest ta struktura JSON:

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

Elementy <Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>

Używaj tych elementów razem.

Jeśli ustawisz wartość true, zawartość elementu XML zostanie przekonwertowana na właściwość ciągu znaków.

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

W przypadku tego kodu XML:

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

Jeśli parametr TextAlwaysAsProperty ma wartość true, a parametr TextNodeName ma wartość TEXT, generowana jest ta struktura JSON:

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

Jeśli wartość TextAlwaysAsProperty to false, a wartość TextNodeName to TEXT, generowana jest ta struktura JSON:

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

Elementy <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

Używaj tych elementów razem.

Umożliwia grupowanie wartości w bloku JSON i dodawanie prefiksów do nazw atrybutów.

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

Przyjrzyj się temu przykładowi XML:

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

Jeśli oba atrybuty (AttributeBlockName i AttributePrefix) są określone zgodnie z przykładem XML do JSON, generowana jest ta struktura JSON:

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

Jeśli określono tylko AttributeBlockName, generowana jest ta struktura JSON:

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

Jeśli określono tylko AttributePrefix, generowana jest ta struktura JSON:

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

Jeśli nie określono żadnej z tych wartości, generowana jest ta struktura JSON:

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

Elementy <Options>/<OutputPrefix>
<Options>/<OutputSuffix>

Używaj tych elementów razem.

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

Przyjrzyj się temu przykładowi XML:

<a>value</a>

Jeśli oba atrybuty (OutputPrefix i OutputSuffix) są określone zgodnie z przykładem XML do JSON, generowana jest ta struktura JSON:

PREFIX_{
    "a": "value"
}_SUFFIX

Jeśli podano tylko OutputPrefix, generowana jest ta struktura JSON:

PREFIX_{
  "a" : "value"
}

Jeśli podano tylko OutputSuffix, generowana jest ta struktura JSON:

{
  "a" : "value"
}_SUFFIX

Jeśli nie określono ani OutputPrefix, ani OutputSuffix, generowana jest ta struktura JSON:

{
    "a": "value"
}

Element <Options>/<StripLevels>

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

Czasami ładunki XML, takie jak SOAP, mają wiele poziomów nadrzędnych, których nie chcesz uwzględniać w przekonwertowanym pliku JSON. Oto przykładowa odpowiedź SOAP zawierająca wiele poziomów:

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

Zanim przejdziesz do poziomu stanu, miasta, opisu i temperatury, musisz przejść 4 poziomy. Bez użycia <StripLevels> przekonwertowana odpowiedź JSON wyglądałaby tak:

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

Jeśli chcesz usunąć pierwsze 4 poziomy w odpowiedzi JSON, ustaw wartość <StripLevels>4</StripLevels>. Otrzymasz wtedy ten kod JSON:

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

Możesz usunąć poziomy aż do pierwszego elementu, który zawiera wiele elementów podrzędnych. Co to oznacza? Przyjrzyjmy się bardziej złożonemu przykładowi kodu JSON:

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

Poziom 3 w tym przykładzie to GetCityForecastByZIPResponse, który ma tylko 1 element podrzędny. Jeśli użyjesz <StripLevels>3</StripLevels> (usuniesz pierwsze 3 poziomy), kod JSON będzie wyglądać tak:

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

Zwróć uwagę, że element GetCityForecastByZIPResult ma wiele elementów podrzędnych. Ponieważ jest to pierwszy element zawierający wiele elementów podrzędnych, możesz usunąć ten ostatni poziom za pomocą funkcji <StripLevels>4</StripLevels>, która zwróci następujący kod JSON:

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

Poziom 4 jest pierwszym poziomem zawierającym wiele elementów podrzędnych, więc nie można usunąć żadnych poziomów niższych od niego. Jeśli ustawisz poziom usuwania na 5, 6, 7 itd., nadal będziesz otrzymywać powyższą odpowiedź.

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

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

Ta kombinacja elementów pozwala mieć pewność, że wartości z dokumentu XML zostaną umieszczone w tablicy JSON. Jest to przydatne np. wtedy, gdy liczba elementów podrzędnych może się różnić (od jednego do wielu) i chcesz mieć pewność, że wartości są zawsze w tablicy. Dzięki temu kod jest stabilny, ponieważ dane z tablicy możesz pobierać zawsze w ten sam sposób. Na przykład: $.teachers.teacher.studentnames[0] pobiera pierwszą wartość imienia ucznia w tablicy niezależnie od liczby wartości w tablicy.

Cofnijmy się i przyjrzyjmy domyślnemu działaniu konwersji XML na JSON, a potem zobaczmy, jak kontrolować dane wyjściowe za pomocą <TreatAsArray>/<Path>.

Gdy dokument XML zawiera element z wieloma wartościami podrzędnymi (zwykle na podstawie schematu, w którym element ma maxOccurs='unbounded'), zasada XML do JSON automatycznie umieszcza te wartości w tablicy. Na przykład ten blok XML

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

...zostanie automatycznie przekonwertowany na poniższy kod JSON bez specjalnej konfiguracji zasad:

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

Zwróć uwagę, że imiona i nazwiska uczniów są umieszczone w tablicy.

Jeśli jednak w dokumencie XML występuje tylko jeden uczeń, zasada XML do JSON automatycznie traktuje wartość jako pojedynczy ciąg znaków, a nie tablicę ciągów znaków, jak pokazano w tym przykładzie:

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

W poprzednich przykładach podobne dane były konwertowane w różny sposób – raz jako tablica, a raz jako pojedynczy ciąg znaków. W tym miejscu element <TreatAsArray>/<Path> umożliwia kontrolowanie danych wyjściowych. Możesz na przykład zadbać o to, aby imiona uczniów były zawsze umieszczane w tablicy, nawet jeśli jest tylko jedna wartość. Aby to skonfigurować, wskaż ścieżkę do elementu, którego wartości chcesz umieścić w tablicy, w ten sposób:

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

Powyższa konfiguracja spowoduje zapisanie pliku JSON w ten sposób:

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

Zwróć uwagę, że student1 jest teraz w tablicy. Teraz, niezależnie od tego, czy jest jeden uczeń, czy wielu, możesz pobrać ich z tablicy JSON w kodzie za pomocą tego wyrażenia JSONPath:$.teachers.teacher.studentnames.name[0]

Element <Path> ma też atrybut unwrap, który został opisany w następnej sekcji.

Atrybuty

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

Więcej przykładów i szczegółowe informacje o tej funkcji znajdziesz w tym artykule na forum Apigee: Community tutorial: The TreatAsArray option in the XML to JSON policy (Samouczek społeczności: opcja TreatAsArray w zasadach XML do JSON).

<Format>

Format umożliwia kontrolowanie konwersji z XML na JSON. Wpisz nazwę wstępnie zdefiniowanego szablonu, który zawiera konkretną kombinację elementów opcji opisanych w tym temacie. Wstępnie zdefiniowane formaty to: xml.com, yahoo, google, badgerFish.

Użyj elementu <Format> lub grupy <Options>. Nie możesz używać jednocześnie <Format> i <Options>.

Poniżej znajdziesz definicje formatów każdego predefiniowanego szablonu.

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>

Składnia elementu:

<Format>yahoo</Format>

Schematy

Odniesienie do błędu

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego tę zasadę.

Zmienne błędów

Te zmienne są ustawiane po wystąpieniu błędu działania. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Przykładowa reguła błędu

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

Powiązane artykuły

JSON do XML: zasady JSON do XML