Zasada XMLtoJSON

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Co

Ta zasada konwertuje wiadomości z formatu extensible Markup Language (XML) na JavaScript Object Notation (JSON), który daje kilka opcji kontrolowania sposobu działania wiadomości dokonali konwersji.

Zakładając, że intencją jest przekonwertowanie odpowiedzi w formacie XML na format JSON odpowiedź, zasada będzie dołączona do przepływu odpowiedzi (np. Response / ProxyEndpoint / Postflow).

Informacje

W typowym scenariuszu zapośredniczenia zasady z JSON na XML w przepływie żądań przychodzących są często w połączeniu z zasadą XML na JSON w przepływie odpowiedzi wychodzących. Dzięki takiemu połączeniu zasad interfejs JSON API może być widoczny dla usług backendu, które natywnie obsługują tylko format XML.

Na potrzeby scenariuszy, w których interfejsy API są wykorzystywane przez różne aplikacje klienckie, które mogą wymagać kodu JSON lub XML, format odpowiedzi można ustawić dynamicznie, konfigurując format JSON na XML i XML na JSON warunkowego wykonania. Zobacz Zmienne i warunki przepływu , by zademonstrować taki scenariusz.

Przykłady

Szczegółowe informacje o konwertowaniu plików 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>

<XMLtoJSON> atrybuty

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

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

<Source> element

zmienną, żądanie lub odpowiedź zawierającą komunikat XML, na który chcesz przekonwertować kod. JSON.

Nagłówek HTTP Content-type komunikatu źródłowego musi być ustawiony na application/xml; w przeciwnym razie zasada nie jest egzekwowana.

Jeśli <Source> nie jest zdefiniowany, jest traktowany jako komunikat (rozwiązujący żądania, gdy zasada jest połączona z przepływem żądania, lub w odpowiedzi, gdy zasada jest dołączona w procesie odpowiedzi).

Jeśli zmiennej źródłowej nie można rozpoznać lub przechodzi się do typu innego niż wiadomość, zasada powoduje zgłoszenie błędu.

<Source>response</Source>

<OutputVariable> element

Przechowuje dane wyjściowe konwersji w formacie XML na format JSON. Jest to zwykle ta sama wartość co parametr czyli zwykle odpowiedź XML jest konwertowana na odpowiedź JSON.

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

Jeśli nie określisz wartości OutputVariable, source będzie traktowana jako OutputVariable Jeśli np. source to response, to OutputVariable przyjmuje domyślną wartość response.

<OutputVariable>response</OutputVariable>

<Options>

Opcje dają Ci kontrolę nad konwersją z XML na JSON. Użyj <Options>, która umożliwia dodawanie określonych ustawień konwersji, lub <Format>, który pozwala odwołać się do szablonu wstępnie zdefiniowanych opcji. Nie możesz używać jednocześnie <Options> i <Format>

Jeśli pole <Format> nie jest używane, pole <Options> jest wymagane.

<Options>/<RecognizeNumber> element

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

<RecognizeNumber>true</RecognizeNumber>

Przyjrzyjmy się temu przykładowi kodu XML:

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

Jeśli true, jest konwertowany na:

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

Jeśli false, jest konwertowany na:

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

<Options>/<RecognizeBoolean> element

Umożliwia konwersji zachowanie wartości logicznych prawda/fałsz, zamiast przekształcania wartości ciągi tekstowe.

<RecognizeBoolean>true</RecognizeBoolean>

Dla tego przykładowego kodu XML:

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

Jeśli true, jest konwertowany na:

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

Jeśli false, jest konwertowany na:

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

<Options>/<RecognizeNull> element

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, jest konwertowany na:

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

Jeśli false, jest konwertowany na:

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

<Options>/<NullValue> element

Wskazuje wartość, do której powinny być stosowane rozpoznane wartości null w komunikacie źródłowym dokonali konwersji. Domyślną wartością jest null. Ta opcja działa tylko jeśli 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>

Przyjrzyjmy się temu przykładowi kodu XML:

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

Jeśli nie określono NamespaceSeparator, zostanie użyta poniższa struktura JSON wygenerowano:

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

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

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

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName> elementy

Używaj tych elementów razem.

Jeśli ma wartość true, zawartość elementu XML jest konwertowana na ciąg znaków. usłudze.

<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 i TextNodeName w postaci TEXT, zostanie wygenerowana ta struktura JSON:

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

Jeśli TextAlwaysAsProperty ma wartość false i TextNodeName została określona jako TEXT, ta struktura JSON to wygenerowano:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elementy

Używaj tych elementów razem.

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

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

Przyjrzyjmy się temu przykładowi kodu XML:

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

Jeśli oba atrybuty (AttributeBlockName i AttributePrefix) są określony zgodnie z definicją w przykładowym pliku XML na JSON, zostanie wygenerowana następująca struktura JSON:

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

Jeśli określono tylko AttributeBlockName, to poniższa struktura JSON jest wygenerowano:

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

Jeśli określono tylko AttributePrefix, to poniższa struktura JSON jest wygenerowano:

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

Jeśli nie podasz żadnej z tych wartości, zostanie wygenerowana ta struktura JSON:

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

<Options>/<OutputPrefix>
<Options>/<OutputSuffix> elementy

Używaj tych elementów razem.

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

Przyjrzyjmy się temu przykładowi kodu XML:

<a>value</a>

Jeśli określono oba atrybuty (OutputPrefix i OutputSuffix) zgodnie z definicją w przykładowym pliku XML na JSON, zostanie wygenerowana następująca struktura JSON:

PREFIX_{
    "a": "value"
}_SUFFIX

Jeśli podasz tylko OutputPrefix, generowana zostanie ta struktura JSON:

PREFIX_{
  "a" : "value"
}

Jeśli podasz tylko OutputSuffix, generowana zostanie ta struktura JSON:

{
  "a" : "value"
}_SUFFIX

Jeśli nie określono ani OutputPrefix, ani OutputSuffix, następujący Jest generowana struktura JSON:

{
    "a": "value"
}

<Options>/<StripLevels> element

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

Czasami ładunki XML, takie jak SOAP, mają wiele poziomów nadrzędnych, których nie chcesz uwzględniać przekonwertowano plik 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 dojdziesz do poziomu stanu, miasta, opisu i temperatury, musisz przejść 4 poziomy. Bez użycia funkcji <StripLevels> przekonwertowana odpowiedź JSON będzie wyglądać tak: to:

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

Aby usunąć te pierwsze 4 poziomy w odpowiedzi JSON, ustaw <StripLevels>4</StripLevels>, dzięki czemu zyskasz: Plik JSON:

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

Możesz usuwać poziomy aż do pierwszego elementu zawierającego wiele elementów podrzędnych. Zastosowanie to znaczy? Spójrzmy na bardziej złożony przykład 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 jeden dziecka. Jeśli więc chcesz użyć <StripLevels>3</StripLevels> (usuń pierwszych 3 poziomach), kod JSON będzie wyglądał tak:

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

Zwróć uwagę, że GetCityForecastByZIPResult ma kilka elementów podrzędnych. Jest to pierwszego elementu zawierającego wiele elementów podrzędnych, możesz usunąć ten ostatni poziom za pomocą funkcji <StripLevels>4</StripLevels>, dzięki którym uzyskasz te korzyści: Plik JSON:

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

Poziom 4 to pierwszy poziom zawierający wiele dzieci, więc nie możesz usunąć żadnych poziomów jest niższa niż ta wartość. Jeśli ustawisz poziom paska na 5, 6, 7 itd., nadal będziesz widzieć odpowiedź powyżej.

<Options>/<TreatAsArray>/<Path> element

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

Ta kombinacja elementów zapewnia, że wartości z dokumentu XML są umieszczane w pliku JSON . Jest to przydatne np. wtedy, gdy liczba elementów podrzędnych może się różnić (od 1 do wielu) i chcesz się upewnić, że wartości są zawsze w tablicy. Dzięki temu Twoje dane kod jest stabilny, ponieważ za każdym razem dane z tablicy można pobierać w ten sam sposób. Dla: przykład: $.teachers.teacher.studentnames[0] pobiera wartość pierwszego imienia ucznia niezależnie od liczby wartości w tablicy.

Cofnijmy się i spójrzmy na domyślne zachowanie XML na JSON, a potem zobaczmy, jak steruj wyjściem za pomocą <TreatAsArray>/<Path>.

Gdy dokument XML zawiera element z wieloma wartościami podrzędnymi (zwykle na podstawie schematu gdzie maxOccurs='unbounded' elementu), zasada XML na JSON automatycznie umieszcza te wartości w tablicy. Na przykład następujący blok XML:

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

...jest automatycznie konwertowany na następujący kod JSON bez specjalnej zasady Konfiguracja:

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

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

Jeśli jednak w dokumencie XML jest tylko jeden uczeń, zasada XML na JSON automatycznie traktuje wartość jako pojedynczy ciąg, a nie tablicę ciągów, jak to widać w poniższym przykładzie przykład:

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

W poprzednich przykładach podobne dane zostały skonwertowane w inny sposób: raz jako tablica, drugi jako pojedynczy ciąg znaków. Element <TreatAsArray>/<Path> pozwala kontrolujesz wyjście. Możesz na przykład określić, że imiona i nazwiska uczniów są zawsze wpisywane tablica, nawet jeśli istnieje tylko jedna wartość. Aby to zrobić, określ ścieżkę do , którego wartości chcesz umieścić w tablicy, np.:

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

Powyższa konfiguracja zapisze kod JSON w taki sposób:

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

Zwróć uwagę, że uczeń1 jest teraz w tablicy. Niezależnie od tego, czy jest uczniów, możesz pobrać je z tablicy JSON w swoim kodzie, korzystając z tej ścieżki JSONPath: $.teachers.teacher.studentnames.name[0]

Element <Path> ma też atrybut unwrap, jak opisano w przejdź do 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 przewodnik po funkcjach 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 XML na JSON. Wpisz nazwę wstępnie zdefiniowanego elementu 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żyć <Format> i <Options>.

Poniżej znajdziesz definicje formatu każdego wstępnie zdefiniowanego 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

Informacje o błędzie

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

Z JSON na XML: z JSON na XML