Criterio XMLtoJSON

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza la documentazione di Apigee Edge.

Cosa

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

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

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.

Informazioni

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

Per 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 da JSON a XML e da XML a JSON e i criteri da eseguire in modo condizionale. Consulta la sezione Variabili e condizioni dei flussi per un'implementazione di questo scenario.

Esempi

Per una discussione dettagliata sulla conversione tra JSON e XML, consulta questo articolo.

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

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

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

&lt;Source&gt; elemento

La variabile che specifica il messaggio XML in cui vuoi convertire JSON.

L'intestazione del tipo di contenuto HTTP del messaggio di origine deve essere impostata su application/xml, altrimenti il criterio non viene applicato.

Se <Source> non viene definito, viene trattato come message, che si risolve in request quando il criterio viene collegato a un flusso di richieste oppure response quando il criterio è collegato a un flusso di risposta.

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

<Source>response</Source>

&lt;OutputVariable&gt; elemento

Specifica dove archiviare l'output della conversione in formato XML in formato JSON. In genere, questo elemento non è incluso nella configurazione dei criteri.

Apigee analizza il payload del messaggio XML specificato in Source, lo converte in JSON, memorizza il risultato nel payload di OutputVariable e imposta l'intestazione HTTP Content-type del messaggio OutputVariable su application/json.

Se OutputVariable non è specificato, viene utilizzato il valore di Source per impostazione predefinita. Ad esempio, se source è response, OutputVariable avrà come valore predefinito response.

<OutputVariable>response</OutputVariable>

<Options>

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

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

<RecognizeNumber>true</RecognizeNumber>

Considera l'esempio XML che segue:

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

Se RecognizeNumber è true, il criterio lo converte in:

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

Se RecognizeNumber è false, il criterio lo converte in:

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

Elemento <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 RecognizeBoolean è true, il criterio lo converte in:

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

Se RecognizeBoolean è false, il criterio lo converte in:

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

&lt;RecognizeNull&gt; elemento

Consente di convertire i valori vuoti in valori null.

<RecognizeNull>true</RecognizeNull>

Per il seguente XML:

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

Se RecognizeNull è true e non è presente l'opzione NullValue, questo XML viene convertito in:

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

Se RecognizeNull è false, questo codice XML viene convertito in:

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

&lt;NullValue&gt; elemento

Indica il valore in 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>

Per il seguente XML:

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

Se RecognizeNull è true e NullValue non è specificato, questo XML viene convertito in:

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

Se RecognizeNull è true e NullValue è not-present, questo codice XML viene convertito in:

{
  "a": {
    "b": "not-present",
    "c": "value"
  }
}

Opzioni dello spazio dei nomi

Per impostazione predefinita, questo criterio omette gli spazi dei nomi XML nel file JSON generato. Per specificare che gli spazi dei nomi nel documento XML devono essere tradotti nel JSON generato, 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"
    }
}

Opzioni di testo

Usa questi elementi insieme.

      <TextAlwaysAsProperty>true|false</TextAlwaysAsProperty>
      <TextNodeName>TEXT</TextNodeName>

Quando il criterio rileva un elemento XML che contiene un solo nodo di testo come figlio, Il criterio converte i contenuti testuali dell'elemento XML in una proprietà nell'hash JSON.

Quando il criterio rileva un elemento XML che contiene più elementi secondari di contenuti misti, queste opzioni consentono di controllare il JSON di output dei nodi di testo figlio.

Ad esempio, considera questa configurazione delle norme:

<XMLToJSON name='XMLToJSON-1'>
  <Options>
    <TextAlwaysAsProperty>???</TextAlwaysAsProperty>
    <TextNodeName>#text</TextNodeName>
  </Options>
</XMLToJSON>

Per gli input XML specificati, il criterio genererà queste uscite, a seconda che TextAlwaysAsProperty sia true o false:

<a>value1</a>

{
  "a": "value1"
}

{
  "a": {
    "#text": "value1"
  }
}

<a>value1
  <b>value2</b>
</a>

{
  "a": {
    "#text": "value1\n",
    "b": "value2"
  }
}

{
  "a": {
    "#text": "value1\n",
    "b": {
      "#text": "value2"
    }
  }
}

Opzioni attributo

Questi elementi, insieme, ti consentono di raggruppare i valori degli attributi in un blocco JSON e di 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 specificata 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 applicata la seguente struttura JSON generato:

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

Se viene specificato solo AttributePrefix, viene applicata la seguente struttura JSON generato:

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

&lt;OutputPrefix&gt; e <OutputSuffix> elementi

Utilizza questi elementi insieme per applicare un prefisso e/o un suffisso al JSON generato.

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

Considera il seguente esempio XML:

<a>value</a>

Supponiamo che la configurazione dei criteri sia la seguente:

<XMLToJSON name='XMLToJSON-4'>
  <Options>
    <OutputPrefix>{ "result": </OutputPrefix>
    <OutputSuffix>}</OutputSuffix>
  </Options>
</XMLToJSON>

Viene generata la seguente struttura JSON:

{
  "result": {
    "a": "value"
  }
}

Puoi omettere uno o entrambi i valori OutputPrefix e OutputSuffix.

Utilizzando questi elementi, è possibile generare un file JSON non valido. Ad esempio, utilizzando questo configurazione dei criteri:

<XMLToJSON name='XMLToJSON-4'>
  <Options>
    <OutputPrefix>PREFIX_</OutputPrefix>
  </Options>
</XMLToJSON>

Il criterio genera quanto segue, che non è JSON valido:

PREFIX_{
  "a" : "value"
}

Se la configurazione non specifica né OutputPrefix né OutputSuffix, il criterio genera la seguente struttura JSON:

{
  "a": "value"
}

Elemento <StripLevels>

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

A volte i payload XML, come SOAP, hanno molti livelli padre che non si desidera includere 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>

Prima di arrivare ai livelli Stato, Città, Descrizione e Temperatura, ci sono 4 livelli. Se non utilizzi <StripLevels>, la risposta JSON convertita sarebbe simile a questo:

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

Se vuoi eliminare i primi quattro livelli dalla risposta JSON, devi impostare <StripLevels>4</StripLevels>, che restituisce quanto segue: 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 ne ha solo uno figlio/a. Pertanto, 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
               }  ...

Nota che GetCityForecastByZIPResult ha più elementi secondari. Poiché si tratta primo elemento contenente più elementi secondari, puoi rimuovere quest'ultimo livello utilizzando <StripLevels>4</StripLevels>, che ti fornirà quanto segue JSON:

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

Poiché il livello 4 è il primo livello contenente più elementi secondari, non puoi rimuovere i livelli inferiori. Se imposti il livello della striscia a 5, 6, 7 e così via, continuerai ad avere risposta precedente.

Elemento <TreatAsArray>/<Path>

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

Questa combinazione di elementi ti consente di garantire che i valori di un documento XML vengano sempre tradotti in un array JSON. Questo può essere utile quando il numero di elementi secondari varia a seconda e carichi di lavoro superflui. Il comportamento predefinito di Apigee è convertire più elementi secondari dello stesso nome in un array JSON e singoli elementi secondari in un elemento JSON primitivo. Opzione TreatAsArray assicura che gli elementi secondari vengano sempre tradotti in un array JSON.

L'uso di TreatAsArray può migliorare la struttura del codice successivo che gestisce l'output, perché i dati dell'array vengono restituiti sempre nello stesso modo. Ad esempio, la valutazione di un JSONPath di $.teachers.teacher.studentnames.name[0] restituirà il valore del nome in modo coerente, indipendentemente dal fatto che il file XML originale contenesse uno o più elementi name.

Facciamo un passo indietro e diamo un’occhiata al comportamento predefinito da XML a JSON, quindi scopriamo come controlla l'output utilizzando <TreatAsArray>/<Path>.

Quando un documento XML contiene un elemento con più occorrenze (cosa che può accadere quando lo schema XML specifica maxOccurs='unbounded' per l'elemento), il criterio XML to 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 convertita automaticamente nel seguente JSON senza criteri speciali configurazione:

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

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

Tuttavia, se nel documento XML compare solo uno studente, il criterio da XML a JSON automaticamente tratta il valore come una singola stringa, non come un array di stringhe, come mostrato di seguito esempio:

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

Negli esempi precedenti, dati simili sono stati convertiti in modo diverso, una volta in un array, un'altra in una singola stringa. L'elemento <TreatAsArray>/<Path> consente di controllare l'output per assicurarti che i nomi degli studenti vengano sempre convertiti in un array anche se è presente un solo valore. Per farlo, identifica il percorso dell'elemento cuyos valori vuoi convertire in un array, come segue:

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

La configurazione riportata sopra genererà il JSON come segue:

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

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

L'elemento <Path> ha anche un attributo unwrap, spiegato 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 delle funzionalità, consulta questo articolo della community Google Cloud.

<Format>

Il formato ti consente di controllare la conversione da XML a JSON. Inserisci il nome di un 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 dei formati 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>

tasso

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

Sintassi dell'elemento:

<Format>yahoo</Format>

Schemi

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Esempio di risposta di errore

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

Esempio di regola di errore

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