Norme di JSONtoXML

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Questo criterio consente di convertire i messaggi dal formato JSON (JavaScript Object Notation) in XML (extensible markup language), offrendo diverse opzioni per controllare la modalità di conversione dei messaggi.

Il criterio è particolarmente utile se vuoi trasformare i messaggi utilizzando XSL. Dopo aver convertito un payload JSON in XML, utilizza il criterio di trasformazione XSL con un foglio di stile personalizzato per eseguire la trasformazione necessaria.

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'intenzione sia convertire una richiesta in formato JSON in una richiesta in formato XML, il criterio verrà collegato a un flusso di richieste (ad es. Request / ProxyEndpoint/PostFlow).

Esempi

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

Conversione di una richiesta

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

Questa configurazione prende il messaggio di richiesta in formato JSON come origine e crea un messaggio in formato XML che viene compilato nella variabile request OutputVariable. Apigee utilizza automaticamente i contenuti di questa variabile come messaggio per il passaggio di elaborazione successivo.

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>

Attributi <JSONToXML>

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ò 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 su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto 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à applicato anche se rimane collegato a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Ritirato

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

Elemento <Source>

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

Elemento <OutputVariable>

Memorizza l'output della conversione del 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 l'intestazione HTTP Content-type del messaggio in formato XML è impostata su text/xml;charset=UTF-8.

Se OutputVariable non è specificato, source viene trattato come OutputVariable. Ad esempio, se source è request, 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 di dichiarazione XML dall'output. Se vuoi, puoi visualizzare una riga di dichiarazione XML nella parte superiore di un documento XML. Un esempio tipico è il seguente: 

<?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 per questa opzione è false, il che significa che il criterio includerà la riga di dichiarazione XML nell'output. La seguente impostazione configurerà il criterio in modo da omettere la dichiarazione XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Non è possibile modificare o influenzare i contenuti della riga di dichiarazione XML tramite la 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 ambito nel codice XML prodotto dal criterio. Ciò significa che il JSON di origine deve fornire una proprietà che possa 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>

<ObjectRootElementName> specifica il nome dell'elemento principale quando esegui la conversione da JSON, che non ha un elemento principale nominato, a XML.

Ad esempio, se il JSON viene visualizzato come segue:

{
  "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> ti consente di specificare quando gli elementi JSON vengono trasformati 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>

<Options>/<ArrayRootElementName>
Elemento <Options>/<ArrayItemElementName>

Converte un array JSON in un elenco di elementi XML con nomi di elementi principali e secondari specificati.

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>

<Options>/<Indent>

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

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

L'output senza rientro è:

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

Con l'a capo abilitato, l'output è:

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

Elemento <Options>/<TextNodeName>

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 TextNodeName non è specificato, 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 del codice XML non valido che potrebbe causare problemi con un analizzatore sintattico, questa impostazione sostituisce tutti gli elementi JSON che producono XML non valido con la stringa. Ad esempio, la seguente 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 JSON to XML nel flusso di richieste in entrata viene spesso associato a un criterio XMLtoJSON nel flusso di risposta in uscita. Combinando i criteri in questo modo, è possibile esporre un'API JSON per i servizi che supportano nativamente solo XML.

Spesso è utile applicare il criterio JSON predefinito (vuoto) a XML e aggiungere in modo iterativo gli elementi di configurazione in base alle esigenze.

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 Voci e condizioni del flusso 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. 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.

Codice guasto 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 definito nell'elemento <Source> e nell'elemento <OutputVariable> non è lo stesso. È obbligatorio che il tipo di variabili contenute nell'elemento <Source> e nell'elemento <OutputVariable> corrisponda. I tipi validi sono message e string.
steps.jsontoxml.InvalidSourceType 500 Questo errore si verifica se il tipo di variabile utilizzata 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 criterio JSON to XML è di tipo stringa e l'elemento <OutputVariable> non è definito. L'elemento <OutputVariable> è obbligatorio quando la variabile definita nell'elemento <Source> è di tipo stringa.
steps.jsontoxml.SourceUnavailable 500 Questo errore si verifica se la variabile message specificata nell'elemento <Source> del criterio JSON to XML è:
  • Al di fuori dell'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, consulta Informazioni importanti 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 dell'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