Criterio XMLtoJSON

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Questo criterio converte i messaggi dal formato Extensible Markup Language (XML) in JavaScript JSON (Object Notation), che offre diverse opzioni per controllare il modo in cui i messaggi vengono convertito.

Supponendo che lo scopo sia convertire una risposta in formato XML in un la risposta, il criterio viene 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 è spesso abbinate a un criterio da XML a JSON sul flusso di risposta in uscita. Combinando i criteri in questo modo, un'API JSON può essere esposta per i servizi di backend che supportano in modo nativo solo XML.

Per scenari in cui le API vengono utilizzate da diverse app client che possono 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 Variabili e condizioni di flusso per un'implementazione di questo scenario.

Esempi

Per una discussione dettagliata sulla conversione tra JSON e XML, visita 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>

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>

<XMLtoJSON> attributi

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

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

<Source> elemento

La variabile, la richiesta o la risposta, contenente il messaggio XML da convertire JSON.

L'intestazione Content-type HTTP del messaggio di origine deve essere impostata su application/xml, altrimenti il criterio non viene applicato in modo forzato.

Se <Source> non viene definito, viene considerato come messaggio (e viene risolto da richiedere quando il criterio è collegato a un flusso di richiesta o una risposta 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>

<OutputVariable> elemento

Archivia l'output della conversione in formato da XML a JSON. Di solito corrisponde al valore , ovvero di solito la risposta XML viene convertita in una risposta JSON.

Il payload del messaggio XML viene analizzato e convertito in JSON e il tipo di contenuto HTTP l'intestazione del messaggio in formato XML sia impostata su application/json.

Se OutputVariable non viene specificato, source viene considerato OutputVariable. Ad esempio, se source è response, poi il valore predefinito di OutputVariable è 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 oppure il <Format>, che ti consente di fare riferimento a un modello di predefinite. Non puoi utilizzare sia <Options> che <Format>.

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

<Options>/<RecognizeNumber> elemento

Se impostato su 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 true, converte in:

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

Se false, converte in:

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

<Options>/<RecognizeBoolean> elemento

Consente alla conversione di mantenere i valori booleani vero/falso anziché convertire i valori in stringhe.

<RecognizeBoolean>true</RecognizeBoolean>

Per il seguente esempio XML:

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

Se true, converte in:

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

Se false, converte in:

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

<Options>/<RecognizeNull> 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 true, converte in:

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

Se false, converte in:

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

<Options>/<NullValue> elemento

Indica il valore a cui devono essere assegnati i valori null riconosciuti nel messaggio di origine convertito. Per impostazione predefinita, il valore è null. Questa opzione è valida solo se RecognizeNull è vero.

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elementi

Usa 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 applicata la seguente struttura JSON generato:

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

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName> elementi

Usa questi elementi insieme.

Se impostato su true, i contenuti dell'elemento XML vengono convertiti in una stringa proprietà.

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

Per il seguente XML:

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

Se TextAlwaysAsProperty viene 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 il criterio TextAlwaysAsProperty è impostato su false e TextNodeName specificato come TEXT, la seguente struttura JSON è generato:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elementi

Usa 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 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 nessuna delle due opzioni viene specificata, viene generata la seguente struttura JSON:

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

<Options>/<OutputPrefix>
<Options>/<OutputSuffix> elementi

Usa questi elementi insieme.

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

Considera il seguente esempio XML:

<a>value</a>

Se sono specificati entrambi gli attributi (OutputPrefix e OutputSuffix) come definito 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 viene specificato né OutputPrefix né OutputSuffix, quanto segue Viene generata la struttura JSON:

{
    "a": "value"
}

<Options>/<StripLevels> elemento

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

Ci sono 4 livelli prima di raggiungere i livelli Stato, Città, Descrizione e Temperatura. 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 eliminare i livelli fino al primo elemento che contiene più elementi secondari. Che cosa questo significa? Vediamo un esempio 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 il primi tre livelli), il codice JSON sarà simile al seguente:

{
   "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 che contiene più livelli secondari, non puoi rimuovere alcun livello inferiore a questo valore. Se imposti il livello della striscia a 5, 6, 7 e così via, continuerai ad avere risposta precedente.

<Options>/<TreatAsArray>/<Path> elemento

<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 file JSON un array di dati. Questo è utile, ad esempio, quando il numero di elementi secondari può variare (da uno a multipli) e vuoi assicurarti che i valori siano sempre in un array. In questo modo e la stabilità del codice, perché i dati dall'array possono essere acquisiti sempre nello stesso modo. Per esempio: $.teachers.teacher.studentnames[0] ottiene il primo valore del nome dello studente a prescindere dal numero di valori nella matrice.

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ù valori figlio (di solito in base a uno schema) dove maxOccurs='unbounded' dell'elemento), il criterio da XML a JSON automaticamente inserisce 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"
              ]}
           }
      }
}

Nota che i due nomi degli studenti vengono inseriti 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 come array, un'altra come una singola stringa. È qui che l'elemento <TreatAsArray>/<Path> consente controllare l'output. Puoi, ad esempio, assicurarti che i nomi degli studenti siano sempre inseriti anche se è presente un solo valore. La configurazione viene configurata identificando il percorso elemento di cui desideri inserire i valori in un array, in questo modo:

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

La configurazione precedente scriverà il codice JSON in questo modo:

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

Nota che studente1 è ora in un array. Indipendentemente dal fatto che ci siano studenti, puoi recuperarli da un array JSON del tuo codice utilizzando il seguente JSONPath: $.teachers.teacher.studentnames.name[0]

L'elemento <Path> ha anche un attributo unwrap, spiegato in nella prossima sezione.

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: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html.

<Format>

Il formato 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 del formato di ciascun 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

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

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, vedi Cosa devi sapere 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

Da JSON a XML: da JSON a XML norme