Norme di 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) al formato XML (Extensible Markup Language), offrendoti 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 XSL Transform con un foglio di stile personalizzato per eseguire la trasformazione che ti serve.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.

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

Esempi

Per una discussione dettagliata, vedi 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 accetta un messaggio di richiesta in formato JSON come origine e poi crea un messaggio in formato XML che viene inserito in request OutputVariable. Apigee utilizza automaticamente il contenuto 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 queste norme.

<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 Presence
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 su 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 Deprecato

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.
Presence 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 considerato 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>request</Source>
Predefinito richiesta o risposta, a seconda di dove viene aggiunta la policy al flusso del proxy API
Presenza Facoltativo
Tipo messaggio

Elemento <OutputVariable>

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

Il payload del messaggio JSON viene analizzato e convertito in XML e l'intestazione Content-type HTTP 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, OutputVariable ha come valore predefinito request.

<OutputVariable>request</OutputVariable>
Predefinito richiesta o risposta, a seconda di dove viene aggiunta la policy 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. Una riga di dichiarazione XML può facoltativamente essere visualizzata 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 queste norme. Un buon esempio è se prevedi di incorporare l'output di questa policy come frammento in un documento XML più grande. Poiché la dichiarazione deve essere visualizzata una sola volta in un documento e solo nella parte superiore del documento, in questo caso è importante eliminare la riga della dichiarazione XML nel frammento XML.

Il valore predefinito di 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 modellare o influire sui contenuti della riga di dichiarazione XML tramite la configurazione di questo criterio. Il criterio genera sempre testo codificato in UTF-8 e utilizza sempre la versione 1.0 di XML. La riga di dichiarazione, se inclusa, lo riflette.

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

JSON non supporta gli spazi dei nomi, mentre i documenti XML spesso li richiedono. NamespaceBlockName consente di definire una proprietà JSON che funge da origine di una definizione di spazio dei nomi nell'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 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"
   }
}

viene convertito in:

<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 denominato, a XML.

Ad esempio, se il JSON viene visualizzato come:

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

E hai impostato <ObjectRootElementName> come:

<ObjectRootElementName>Root</ObjectRootElementName>

L'XML risultante ha il seguente aspetto:

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

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

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

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

Converte un array JSON in un elenco di elementi XML con i nomi degli elementi padre e figlio 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 indica di non rientrare.

Ad esempio, la seguente impostazione configura la policy in modo da 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 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, l'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 valido che potrebbe causare problemi con un parser, questa impostazione sostituisce qualsiasi elemento JSON che produce 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, una policy JSON to XML nel flusso di richieste in entrata viene spesso abbinata a una policy XMLtoJSON nel flusso di risposte in uscita. Combinando i criteri in questo modo, è possibile esporre un'API JSON per i servizi che supportano in modo nativo solo XML.

Spesso è utile applicare i criteri JSON in XML predefiniti (vuoti) 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 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.

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 Che cosa devi sapere 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