Norme di XMLtoJSON

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Questo criterio converte i messaggi dal formato XML (Extensible Markup Language) a JSON (JavaScript Object Notation), offrendoti diverse opzioni per controllare la modalità di conversione dei messaggi.

Supponendo che l'intento sia quello di convertire una risposta in formato XML in una risposta in formato JSON, il criterio verrà collegato a un flusso di risposta (ad esempio, Response / ProxyEndpoint/PostFlow).

Informazioni

In uno scenario di mediazione tipico, un criterio da JSON a XML nel flusso di richieste in entrata viene spesso abbinato a un criterio da XML a JSON nel flusso di risposte in uscita. Combinando i criteri in questo modo, è possibile esporre un'API JSON per i servizi di backend che supportano in modo nativo solo XML.

Per gli scenari in cui le API vengono utilizzate da diverse app client che potrebbero richiedere JSON o XML, il formato della risposta può essere impostato dinamicamente configurando i criteri di conversione da JSON a XML e da XML a JSON da eseguire in modo condizionale. Per un'implementazione di questo scenario, consulta la sezione Variabili e condizioni del flusso.

Esempi

Per una discussione dettagliata sulla conversione tra JSON e XML, consulta Conversione tra XML e JSON con Apigee: cosa devi sapere.

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

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in queste norme.

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

Attributi <XMLtoJSON>

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Elemento <Source>

La variabile, la richiesta o la risposta che contiene il messaggio XML che vuoi convertire in JSON.

L'intestazione del tipo di contenuto HTTP del messaggio di origine deve essere impostata su application/xml, altrimenti la policy non viene applicata.

Se <Source> non è definito, viene trattato come messaggio (che viene risolto come richiesta quando la policy è collegata a un flusso di richieste o come risposta quando la policy è collegata a un flusso di risposte).

Se la variabile di origine non può essere risolta o viene risolta in un tipo non di messaggio, il criterio genera un errore.

<Source>response</Source>

Elemento <OutputVariable>

Memorizza l'output della conversione dal formato XML a JSON. In genere, questo valore è uguale a quello dell'origine, ovvero la risposta XML viene convertita in una risposta JSON.

Il payload del messaggio XML viene analizzato e convertito in JSON e l'intestazione Content-type HTTP del messaggio in formato XML è impostata su application/json.

Se OutputVariable non è specificato, source viene trattato come OutputVariable. Ad esempio, se source è response, OutputVariable è impostato su response per impostazione predefinita.

<OutputVariable>response</OutputVariable>

<Opzioni>

Le opzioni ti consentono di controllare la conversione da XML a JSON. Utilizza il gruppo <Options>, che ti consente di aggiungere impostazioni di conversione specifiche, o l'elemento <Format>, che ti consente di fare riferimento a un modello di opzioni predefinite. Non puoi utilizzare sia <Options> che <Format>.

<Options> è obbligatorio se non viene utilizzato <Format>.

Elemento <Options>/<RecognizeNumber>

Se è vero, i campi numerici nel payload XML mantengono il formato originale.

<RecognizeNumber>true</RecognizeNumber>

Considera il seguente esempio XML:

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

Se true, viene convertito in:

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

Se false, viene convertito in:

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

Elemento <Options>/<RecognizeBoolean>

Consente alla conversione di mantenere i valori booleani true/false anziché trasformarli in stringhe.

<RecognizeBoolean>true</RecognizeBoolean>

Per il seguente esempio XML:

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

Se true, viene convertito in:

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

Se false, viene convertito in:

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

Elemento <Options>/<RecognizeNull>

Consente di convertire i valori vuoti in valori null.

<RecognizeNull>true</RecognizeNull>

Per il seguente XML:

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

Se true, viene convertito in:

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

Se false, viene convertito in:

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

Elemento <Options>/<NullValue>

Indica il valore a cui devono essere convertiti i valori null riconosciuti nel messaggio di origine. Per impostazione predefinita, il valore è null. Questa opzione è efficace solo se RecognizeNull è true.

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

Utilizza questi elementi insieme.

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

Considera il seguente esempio XML:

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

Se NamespaceSeparator non è specificato, viene generata la seguente struttura JSON:

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

Se gli elementi NamespaceBlockName, DefaultNamespaceNodeName e NamespaceSeparator sono specificati come #namespaces, & e ***, rispettivamente, viene generata la seguente struttura JSON:

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

Elementi <Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>

Utilizza questi elementi insieme.

Se impostato su true, il contenuto dell'elemento XML viene convertito in una proprietà stringa.

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

Per il seguente XML:

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

Se TextAlwaysAsProperty è impostato su true e TextNodeName specificato come TEXT, viene generata la seguente struttura JSON:

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

Se TextAlwaysAsProperty è impostato su false e TextNodeName specificato come TEXT, viene generata la seguente struttura JSON:

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

Elementi <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

Utilizza questi elementi insieme.

Consente di raggruppare i valori in un blocco JSON e aggiungere prefissi ai nomi degli attributi.

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

Considera il seguente esempio XML:

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

Se entrambi gli attributi (AttributeBlockName e AttributePrefix) sono specificati come definito nell'esempio da XML a JSON, viene generata la seguente struttura JSON:

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

Se viene specificato solo AttributeBlockName, viene generata la seguente struttura JSON:

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

Se viene specificato solo AttributePrefix, viene generata la seguente struttura JSON:

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

Se non viene specificato nessuno dei due, viene generata la seguente struttura JSON:

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

Elementi <Options>/<OutputPrefix>
<Options>/<OutputSuffix>

Utilizza questi elementi insieme.

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

Considera il seguente esempio XML:

<a>value</a>

Se entrambi gli attributi (OutputPrefix e OutputSuffix) sono specificati come definiti nell'esempio da XML a JSON, viene generata la seguente struttura JSON:

PREFIX_{
    "a": "value"
}_SUFFIX

Se viene specificato solo OutputPrefix, viene generata la seguente struttura JSON:

PREFIX_{
  "a" : "value"
}

Se viene specificato solo OutputSuffix, viene generata la seguente struttura JSON:

{
  "a" : "value"
}_SUFFIX

Se non vengono specificati né OutputPrefix né OutputSuffix, viene generata la seguente struttura JSON:

{
    "a": "value"
}

Elemento <Options>/<StripLevels>

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

A volte i payload XML, come SOAP, hanno molti livelli principali che non vuoi includere nel JSON convertito. Ecco un esempio di risposta SOAP contenente molti livelli:

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

Ci sono 4 livelli prima di arrivare al livello Stato, Città, Descrizione e Temperatura. Senza utilizzare <StripLevels>, la risposta JSON convertita sarebbe simile a questa:

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

Se vuoi rimuovere i primi quattro livelli nella risposta JSON, imposta <StripLevels>4</StripLevels>, che ti darà il seguente JSON:

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

Puoi rimuovere i livelli fino al primo elemento che contiene più elementi secondari. Che cosa significa? Vediamo un esempio di JSON più complesso:

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

Il livello 3 in questo esempio è GetCityForecastByZIPResponse, che ha un solo figlio. Quindi, se utilizzi <StripLevels>3</StripLevels> (rimuovi i primi tre livelli), il JSON avrà il seguente aspetto:

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

Tieni presente che GetCityForecastByZIPResult ha più figli. Poiché è il primo elemento contenente più elementi secondari, puoi rimuovere questo ultimo livello utilizzando <StripLevels>4</StripLevels>, che ti darà il seguente JSON:

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

Poiché il livello 4 è il primo livello contenente più figli, non puoi rimuovere livelli inferiori. Se imposti il livello della striscia su 5, 6, 7 e così via, continuerai a ricevere la risposta riportata sopra.

Elemento <Options>/<TreatAsArray>/<Path>

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

Questa combinazione di elementi ti consente di assicurarti che i valori di un documento XML vengano inseriti in un array JSON. Ciò è utile, ad esempio, quando il numero di elementi secondari può variare (da uno a più) e vuoi assicurarti che i valori siano sempre in un array. In questo modo, il codice rimane stabile perché puoi ottenere i dati dall'array sempre nello stesso modo. Ad esempio: $.teachers.teacher.studentnames[0] ottiene il primo valore del nome dello studente nell'array, indipendentemente dal numero di valori nell'array.

Facciamo un passo indietro ed esaminiamo il comportamento predefinito di XML in JSON, quindi scopriamo come controllare l'output utilizzando <TreatAsArray>/<Path>.

Quando un documento XML contiene un elemento con più valori secondari (di solito in base a uno schema in cui l'elemento maxOccurs='unbounded'), il criterio XML in JSON inserisce automaticamente questi valori in un array. Ad esempio, il seguente blocco XML

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

...viene convertito automaticamente nel seguente JSON senza una configurazione speciale dei criteri:

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

Tieni presente che i due nomi degli studenti sono inseriti in un array.

Tuttavia, se nel documento XML è presente un solo studente, il criterio XML in JSON considera automaticamente il valore come una singola stringa, non come un array di stringhe, come mostrato nel seguente esempio:

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

Negli esempi precedenti, dati simili sono stati convertiti in modo diverso, una volta come array e un'altra come singola stringa. È qui che l'elemento <TreatAsArray>/<Path> ti consente di controllare l'output. Ad esempio, puoi assicurarti che i nomi degli studenti vengano sempre inseriti in un array anche se è presente un solo valore. Per configurare questa opzione, identifica il percorso dell'elemento di cui vuoi inserire i valori in un array, come segue:

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

La configurazione precedente scriverebbe il file JSON nel seguente modo:

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

Nota che student1 ora si trova in un array. Ora, indipendentemente dal fatto che ci siano uno o più studenti, puoi recuperarli da un array JSON nel tuo codice utilizzando il seguente JSONPath: $.teachers.teacher.studentnames.name[0]

L'elemento <Path> ha anche un attributo unwrap, illustrato nella sezione successiva.

Attributi

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

Per altri esempi e una procedura dettagliata della funzionalità, consulta questo articolo della community Apigee: Tutorial della community: l'opzione TreatAsArray nel criterio XML to JSON.

<Format>

Il formato ti consente di controllare la conversione da XML a JSON. Inserisci il nome di un modello predefinito che contiene una combinazione specifica di elementi Opzioni descritti in questo argomento. I formati predefiniti includono: xml.com, yahoo, google, badgerFish.

Utilizza l'elemento <Format> o il gruppo <Options>. Non puoi utilizzare sia <Format> che <Options>.

Di seguito sono riportate le definizioni del formato di ogni modello predefinito.

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>

Sintassi dell'elemento:

<Format>yahoo</Format>

Schemi

Messaggi di errore

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>

Argomenti correlati

JSON to XML: JSON to XML policy