Criterio JSONtoXML

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Questo criterio converte i messaggi dal formato JSON (JavaScript Object Notation) in messaggi estensibili linguaggio di markup (XML), che offre varie opzioni per controllare la modalità di conversione dei messaggi.

Il criterio è particolarmente utile se vuoi trasformare i messaggi utilizzando XSL. Dopo il giorno convertendo un payload JSON in XML, utilizza il criterio XSL Transform con un foglio di stile personalizzato per eseguire la trasformazione di cui hai bisogno.

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.

Supponendo che l'intento sia convertire una richiesta in formato JSON in una richiesta in formato XML, il criterio viene collegato a un flusso di richiesta (ad esempio Request / ProxyEndpoint / PostFlow).

Esempi

Per una discussione dettagliata, vedi Conversione da XML a JSON con Apigee: quello che devi sapere.

Conversione di una richiesta in corso...

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

Questa configurazione prende il messaggio di richiesta in formato JSON come origine e poi crea un Messaggio in formato XML compilato nell'elemento OutputVariable request. Apigee utilizza automaticamente i contenuti di questa variabile come messaggio per la successiva fase di elaborazione.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in questo criterio.

<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1">
    <DisplayName>JSON to XML 1</DisplayName>
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
    <Options>
        <OmitXmlDeclaration>false</OmitXmlDeclaration>
        <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
        <NamespaceSeparator>:</NamespaceSeparator>
        <AttributeBlockName>#attrs</AttributeBlockName>
        <AttributePrefix>@</AttributePrefix>
        <ObjectRootElementName>Root</ObjectRootElementName>
        <ArrayRootElementName>Array</ArrayRootElementName>
        <ArrayItemElementName>Item</ArrayItemElementName>
        <Indent>false</Indent>
        <TextNodeName>#text</TextNodeName>
        <NullValue>I_AM_NULL</NullValue>
        <InvalidCharsReplacement>_</InvalidCharsReplacement>
    </Options>
</JSONToXML>

&lt;JSONToXML&gt; attributi

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno del criterio. Il valore dell'attributo name può Deve contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta il valore su false per restituire un errore quando un criterio non funziona. Si tratta di un comportamento previsto comportamento per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta false per disattivare il criterio. Il criterio non verrà applicata anche se rimane collegata a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Ritirato

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

N/D

Se ometti questo elemento, il valore dell'attributo name del criterio è in uso.
Presenza Facoltativo
Tipo Stringa

&lt;Source&gt; elemento

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

Se <Source> non è definito, viene trattato come messaggio (che si risolve in richiesta quando il criterio è associato a un flusso di richieste o in risposta quando il criterio è associato a un flusso di risposte).

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

<Source>request</Source>
Predefinito richiesta o risposta, in base a dove viene aggiunto il criterio al flusso del proxy API
Presenza Facoltativo
Tipo messaggio

&lt;OutputVariable&gt; elemento

Archivia l'output della conversione in formato JSON in XML. Di solito è lo stesso valore dell'origine, ovvero in genere una richiesta JSON viene convertita in una richiesta XML.

Il payload del messaggio JSON viene analizzato e convertito in XML e il tipo di contenuto HTTP l'intestazione del messaggio in formato XML sia impostata su text/xml;charset=UTF-8.

Se OutputVariable non viene specificato, source viene considerato OutputVariable. Ad esempio, se source è request, poi il valore predefinito di OutputVariable è request.

<OutputVariable>request</OutputVariable>
Predefinito richiesta o risposta, in base a dove viene aggiunto il criterio al flusso del proxy API
Presenza Questo elemento è obbligatorio quando la variabile definita nell'elemento <Source> è di tipo stringa.
Tipo messaggio

<Options>/<OmitXmlDeclaration>

Specifica di omettere la riga della dichiarazione XML dall'output. Se vuoi, puoi visualizzare una riga di dichiarazione XML nella parte superiore di un documento XML. Ecco un esempio tipico: 

<?xml version="1.0" encoding="UTF-8"?>

In alcuni casi è importante evitare di includere una riga di questo tipo nell'output di questo criterio. Un buon esempio è se prevedi di incorporare l'output di questo criterio come frammento in un documento XML più grande. Poiché la dichiarazione deve apparire una sola volta in un documento e solo nella parte superiore del documento, in questo caso sarebbe importante eliminare la riga di dichiarazione XML nel frammento XML.

Il valore predefinito di questa opzione è false, il che significa il criterio includerà la riga di dichiarazione XML nell'output. Le seguenti configurerà il criterio in modo da omettere la dichiarazione XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Non c'è modo di modellare o influire sui contenuti della riga di dichiarazione XML tramite il metodo configurazione di questo criterio. Il criterio genera sempre testo codificato UTF-8 e utilizza sempre la versione 1.0 di XML. La riga di dichiarazione, se inclusa, rifletterà questo aspetto.

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
Elementi <Options>/<NamespaceSeparator>

JSON non supporta gli spazi dei nomi, mentre i documenti XML spesso li richiedono. NamespaceBlockName ti consente di definire una proprietà JSON che funge da origine di una definizione di spazio dei nomi nel codice XML prodotto dal criterio. Ciò significa che il JSON di origine deve fornire una proprietà che può essere mappata in uno spazio dei nomi previsto dall'applicazione che utilizza l'XML risultante.

Ad esempio, le seguenti impostazioni:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

indica che nel file JSON di origine esiste una proprietà denominata #namespaces che contiene almeno uno spazio dei nomi designato come predefinito. Ad esempio:

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

diventa:

<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers">
  <person>John Smith</person>
  <exp:person>Pedro Cabral</exp:person>
</population>

<Options>/<ObjectRootElementName>

&lt;ObjectRootElementName&gt; specifica il nome dell'elemento radice quando esegui la conversione da JSON, che non ha un nome root in XML.

Ad esempio, se il JSON viene visualizzato come:

{
  "abc": "123",
  "efg": "234"
}

e imposti <ObjectRootElementName> come:

<ObjectRootElementName>Root</ObjectRootElementName>

Il codice XML risultante è il seguente:

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

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

<AttributeBlockName> consente di specificare quando gli elementi JSON vengono convertiti in attributi XML (anziché in elementi XML).

Ad esempio, la seguente impostazione converte le proprietà all'interno di un oggetto denominato #attrs in attributi XML:

<AttributeBlockName>#attrs</AttributeBlockName>

Il seguente oggetto JSON:

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },        
        "occupation" : "explorer",
    }
}

viene convertito nella seguente struttura XML:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<AttributePrefix> converte la proprietà che inizia con il prefisso specificato in attributi XML. Se il prefisso dell'attributo è impostato su @, ad esempio:

<AttributePrefix>@</AttributePrefix>

Converte il seguente oggetto JSON:

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

alla seguente struttura XML:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

&lt;Options&gt;/&lt;ArrayRootElementName&gt;
&lt;Options&gt;/&lt;ArrayItemElementName&gt; elemento

Converte un array JSON in un elenco di elementi XML con l'elemento principale e secondario specificati i nomi degli utenti.

Ad esempio, le seguenti impostazioni:

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

Converte il seguente array JSON:

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

nella seguente struttura XML:

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

&lt;Options&gt;/&lt;Indent&gt;

Specifica di rientrare l'output XML. Il valore predefinito è false che significa non rientrare.

Ad esempio, la seguente impostazione configura il criterio per rientrare l'output:

<Indent>true</Indent>

Se l'input JSON è nel formato:

{"n": [1, 2, 3] }

L'output senza rientro è:

<Array><n>1</n><n>2</n><n>3</n></Array>

Con il rientro attivato, l'output è:

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

&lt;Options&gt;/&lt;TextNodeName&gt; elemento

Converte una proprietà JSON in un nodo di testo XML con il nome specificato. Ad esempio, la seguente impostazione:

<TextNodeName>age</TextNodeName>

converte questo JSON:

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

a questa struttura XML:

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

Se non viene specificato TextNodeName, il codice XML viene generato utilizzando l'impostazione predefinita per un nodo di testo:

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

Elemento <Options>/<NullValue>

Indica un valore nullo. Per impostazione predefinita, il valore è NULL.

Ad esempio, la seguente impostazione:

<NullValue>I_AM_NULL</NullValue>
 Converte il seguente oggetto JSON: 
{"person" : "I_AM_NULL"}

al seguente elemento XML:

<person></person>

Se non viene specificato alcun valore (o un valore diverso da I_AM_NULL) per il valore Null, lo stesso payload viene convertito in:

<person>I_AM_NULL</person>

Elemento <Options>/<InvalidCharsReplacement>

Per facilitare la gestione di XML non validi che potrebbero causare problemi con un parser, questa impostazione sostituisce qualsiasi elemento JSON che produce XML non valido con la stringa. Ad esempio, dell'impostazione:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Converte questo oggetto JSON

{
    "First%%%Name": "John"
}

a questa struttura XML:

<First_Name>John<First_Name>

Note sull'utilizzo

In uno scenario di mediazione tipico, un criterio da JSON a XML nel flusso di richieste in entrata è spesso abbinate a un criterio XMLtoJSON sul flusso di risposta in uscita. Combinando i criteri in questo modo, L'API JSON può essere esposta per i servizi che supportano in modo nativo solo XML.

Spesso è utile applicare il criterio JSON predefinito (vuoto) al criterio XML e aggiungere iterativamente di configurazione degli utenti, se necessario.

Per gli scenari in cui le API vengono utilizzate da diverse app client che potrebbero richiedere JSON e XML, il formato della risposta può essere impostato dinamicamente configurando i criteri JSON to XML e XML to JSON in modo che vengano eseguiti in modo condizionale. Consulta la sezione Variabili e condizioni dei flussi per un'implementazione di questo scenario.

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. È importante conoscere queste informazioni se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, vedi Informazioni importanti sugli errori relativi alle norme Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Causa Correggi
steps.jsontoxml.ExecutionFailed 500 Il payload di input (JSON) è vuoto o l'input (JSON) passato al criterio JSON to XML è invalido o non valido.
steps.jsontoxml.InCompatibleTypes 500 Questo errore si verifica se il tipo di variabile definita nell'elemento <Source> e L'elemento <OutputVariable> non sono uguali. È obbligatorio che il tipo variabili contenute negli elementi <Source> e <OutputVariable> corrispondenze. I tipi validi sono message e string.
steps.jsontoxml.InvalidSourceType 500 Questo errore si verifica se il tipo di variabile utilizzato per definire l'elemento <Source> non è valido. I tipi di variabili validi sono message e string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 Questo errore si verifica se la variabile specificata nell'elemento <Source> del file JSON per Il criterio XML è di tipo stringa e l'elemento <OutputVariable> non è definito. L'elemento <OutputVariable> è obbligatorio quando la variabile definita in <Source> è obbligatorio è di tipo stringa.
steps.jsontoxml.SourceUnavailable 500 Questo errore si verifica se la variabile message specificata nell'elemento <Source> del criterio JSON to XML è:
  • Fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio) o
  • Non può essere risolto (non è definito)

Errori di deployment

Nessuno.

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.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice di errore. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. jsontoxml.JSON-to-XML-1.failed = true

Esempio di risposta di errore

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Esempio di regola di errore

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

Argomenti correlati