Zasada XMLtoJSON

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Co

Ta zasada konwertuje wiadomości z formatu Extensible Markup Language (XML) na format JavaScript Object Notation (JSON), który daje Ci kilka opcji kontrolowania sposobu konwertowania wiadomości.

Zakładając, że intencją jest przekonwertowanie odpowiedzi w formacie XML na odpowiedź w formacie JSON, zasada zostanie dołączona do przepływu odpowiedzi (na przykład Response / ProxyEndpoint / PostFlow).

Informacje

W typowym scenariuszu zapośredniczenia zasady JSON-XML dotyczące przepływu żądań przychodzących są często łączone z zasadą XML do JSON w przepływie odpowiedzi wychodzących. Łącząc zasady w ten sposób, można ujawnić interfejs JSON API dla usług backendu, które natywnie obsługują tylko kod XML.

W sytuacjach, 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 ustawić dynamicznie, konfigurując zasady JSON jako XML i XML na JSON na ich wykonywanie. Implementację tego scenariusza znajdziesz w sekcji Zmienne i warunki przepływu.

Sample

Szczegółowe omówienie konwertowania między formatami JSON i XML znajdziesz na 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>

Odwołanie do elementu

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

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

Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:

Element <DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Source>

Zmienna, żądanie lub odpowiedź zawierające komunikat w formacie XML, który chcesz przekonwertować na format JSON.

Nagłówek HTTP Content-type wiadomości źródłowej musi być ustawiony na application/xml. W przeciwnym razie zasada nie będzie egzekwowana.

Jeśli zasada <Source> nie jest zdefiniowana, jest traktowana jako wiadomość (która przechodzi do żądania, gdy zasada jest dołączona do przepływu żądań lub jako odpowiedź, gdy zasada jest dołączona do procesu odpowiedzi).

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

<Source>response</Source>

Element <outputVariable>

Przechowuje dane wyjściowe konwersji w formacie XML na format JSON. Zwykle jest to wartość taka sama jak wartość źródłowa, 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 ustawiony na application/json.

Jeśli OutputVariable nie jest określony, source jest traktowany jako OutputVariable. Jeśli np. source to response, OutputVariable przyjmuje wartość domyślną response.

<OutputVariable>response</OutputVariable>

<Opcje>

Opcje zapewniają kontrolę nad konwersją z XML na JSON. Użyj grupy <Options>, która pozwala dodać określone ustawienia konwersji, albo elementu <Format>, który umożliwia odwoływanie się do szablonu wstępnie zdefiniowanych opcji. Nie możesz używać jednocześnie właściwości <Options> i <Format>.

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

Element <Options>/<RecognizeNumber>

Jeśli ma wartość true (prawda), pola liczbowe w ładunku XML zachowują swój pierwotny format.

<RecognizeNumber>true</RecognizeNumber>

Przyjrzyj się temu przykładowi XML:

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

Jeśli true zmieni się na:

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

Jeśli false zmieni się na:

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

Element <Options>/<RecognizeBoolean>

Pozwala na zachowanie przez konwersję wartości logicznych prawda i fałsz, 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 zmieni się na:

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

Jeśli false zmieni się 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 zmieni się na:

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

Jeśli false zmieni się na:

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

Element <Options>/<NullValue>

Wskazuje wartość, na którą należy przekonwertować rozpoznawane wartości null z wiadomości źródłowej. Wartość domyślna to null. Ta opcja jest stosowana tylko wtedy, gdy RecognizeNull ma wartość prawda.

<NullValue>not-present</NullValue>

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

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 NamespaceSeparator nie zostanie określony, generowana jest 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"
    }
}

<Options>/<TextzawszeAsProperty>
Elementy <Options>/<TextNodeName>

Używaj tych elementów razem.

Jeśli ma wartość true, zawartość elementu XML jest konwertowana na właściwość ciągu.

<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 TextAlwaysAsProperty ma wartość true, a TextNodeName jest określony jako TEXT, generowana jest ta struktura JSON:

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

Jeśli TextAlwaysAsProperty ma wartość false, a TextNodeName jest określony jako TEXT, generowana jest ta struktura JSON:

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

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

Używaj tych elementów razem.

Umożliwia grupowanie wartości w bloku JSON i dołączanie 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 definicją w przykładowym pliku XML na JSON, zostanie wygenerowana ta struktura JSON:

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

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

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

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

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

Jeśli nie podasz żadnej z nich, zostanie wygenerowana taka struktura JSON:

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

<Opcje>/<outputPrefix>
Elementy <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 definicją w przykładowym pliku XML na JSON, zostanie wygenerowana ta struktura JSON:

PREFIX_{
    "a": "value"
}_SUFFIX

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

PREFIX_{
  "a" : "value"
}

Jeśli określono 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. 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>

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

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

Jeśli chcesz usunąć te pierwsze 4 poziomy odpowiedzi JSON, ustaw <StripLevels>4</StripLevels>, co da ten kod JSON:

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

Poziomy możesz usuwać 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. Ma tylko 1 element podrzędny. Jeśli więc 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
               }  ...

Zauważ, ż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ą właściwości <StripLevels>4</StripLevels>, co da Ci taki kod JSON:

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

Poziom 4 to pierwszy poziom, na którym znajduje się wiele elementów podrzędnych, więc nie możesz usunąć niższych poziomów. Jeśli ustawisz poziom paska na 5, 6, 7 itd., nadal będziesz otrzymywać powyższą odpowiedź.

Element <Options>/<TreatAsSlate>/<Path>

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

Ta kombinacja elementów zapewnia, że wartości z dokumentu XML zostaną umieszczone w tablicy JSON. Jest to przydatne, gdy na przykład liczba elementów podrzędnych może się zmieniać (od 1 do kilku) i chcesz mieć pewność, że wartości zawsze znajdują się w tablicy. Pomaga to zachować stabilność kodu, ponieważ za każdym razem dane z tablicy możesz pobierać w ten sam sposób. Na przykład: $.teachers.teacher.studentnames[0] pobiera pierwszą wartość imienia i nazwiska ucznia w tablicy niezależnie od liczby wartości w tablicy.

Przyjrzyjmy się domyślnemu działaniu XML na JSON, a następnie dowiedzmy się, jak kontrolować dane wyjściowe za pomocą <TreatAsArray>/<Path>.

Gdy dokument XML zawiera element z wieloma wartościami podrzędnymi (zwykle w oparciu o schemat, w którym maxOccurs='unbounded' tego elementu jest), zasada z XML na JSON automatycznie umieszcza te wartości w tablicy. Na przykład poniższy blok XML

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

...zosta automatycznie przekonwertowany na następujący kod JSON bez specjalnej konfiguracji zasad:

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

Zwróć uwagę, że 2 imiony uczniów są umieszczane w tablicy.

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

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

W poprzednich przykładach podobne dane były konwertowane w inny sposób – raz jako tablica, a inne jako pojedynczy ciąg znaków. Tutaj element <TreatAsArray>/<Path> pozwala kontrolować dane wyjściowe. Możesz na przykład zadbać o to, by imiona i nazwiska uczniów zawsze były umieszczane w tablicy, nawet jeśli istnieje tylko jedna wartość. Aby skonfigurować tę opcję, musisz określić ścieżkę do elementu, której wartości chcesz umieścić w tablicy. Na przykład:

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

Powyższa konfiguracja zapisze plik JSON w ten sposób:

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

Zwróć uwagę, że uczeń1 jest teraz w tablicy. Niezależnie od tego, czy jest jeden czy kilku uczniów, możesz ich teraz pobrać z tablicy JSON w kodzie przy użyciu tej ścieżki 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 oraz opis funkcji znajdziesz w tym artykule społeczności Apigee: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html.

<Format>

Format daje Ci kontrolę nad konwersją z formacie XML na JSON. Wpisz nazwę wstępnie zdefiniowanego szablonu, który zawiera określoną 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 właściwości <Format> i <Options>.

Poniżej znajdziesz definicje formatów poszczególnych wstępnie zdefiniowanych szablonów.

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

Informacje o błędach

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

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

Zmienne błędów

Te zmienne są ustawiane, gdy wystąpi błąd środowiska wykonawczego. Więcej informacji znajdziesz w artykule Co musisz wiedzieć 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 to XML: zasady JSON do XML