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) al linguaggio XML (Extensible Markup Language), che offre diverse opzioni per controllare il modo in cui i messaggi vengono convertiti.

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 di cui hai bisogno.

Questo è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di criteri.

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

Esempi

Per una discussione dettagliata, consulta la pagina relativa alla conversione di file 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 un messaggio di richiesta in formato JSON come origine e crea un messaggio in formato XML che viene compilato nella variabile di output request. 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 della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

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

 N/A Obbligatorio
continueOnError

Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche:

 false Facoltativo
enabled

Imposta il criterio su true per applicare il criterio.

Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.

 true Facoltativo
async

Questo attributo è obsoleto.

 false Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta 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/A

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 da convertire in XML.

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

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

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

Elemento <OutputVariable>

Archivia l'output della conversione del formato da JSON a XML. Di solito si tratta dello stesso valore dell'origine, ovvero di solito una richiesta JSON viene convertita in 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 considerato come OutputVariable. Ad esempio, se source è request, il valore predefinito di OutputVariable sarà request.

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

<Opzioni>/<OmitXmlDeclaration>

Specifica di omettere la riga della dichiarazione XML dall'output. Facoltativamente, può essere visualizzata una riga relativa alla 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 questa riga nell'output di questo criterio. Un buon esempio è se prevedi di incorporare l'output di questo criterio sotto forma di 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 della dichiarazione XML nel frammento XML.

Il valore predefinito per questa opzione è false, il che significa che il criterio includerà la riga della dichiarazione XML nell'output. La seguente impostazione configurerà il criterio in modo da omettere la dichiarazione XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Non è possibile modificare i contenuti della riga della dichiarazione XML o modificarli in alcun modo tramite la configurazione di questo criterio. Il criterio genera sempre testo con codifica UTF-8 e utilizza sempre XML versione 1.0, che verrà indicato nella riga della dichiarazione, se inclusa.

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

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 della definizione di uno spazio dei nomi nel file 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 consuma il codice 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"
   }
}

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

<Opzioni>/<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 codice JSON viene visualizzato come segue:

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

Infine, imposti <ObjectRootElementName> come:

<ObjectRootElementName>Root</ObjectRootElementName>

Il codice XML risultante viene visualizzato come:

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

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

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

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

<AttributeBlockName>#attrs</AttributeBlockName>

L'oggetto JSON seguente:

{
    "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à a partire dal prefisso specificato in attributi XML. Dove 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 i nomi degli 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>

<Opzioni>/<Rientro>

Specifica il rientro dell'output XML. Il valore predefinito è false, il che significa che non viene inserito il rientro.

Ad esempio, la seguente impostazione configura il criterio in modo da applicare il rientro all'output:

<Indent>true</Indent>

Se l'input JSON è nel formato:

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

L'output senza rientro sarà:

<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 il seguente codice 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, viene generato il codice XML 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>
Converti 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>/<InvalidCharsSostituzione>

Per facilitare la gestione di XML non validi che potrebbero causare problemi al parser, questa impostazione sostituisce con la stringa tutti gli elementi JSON che producono codice XML non valido. 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 da JSON a XML nel flusso di richieste in entrata è spesso abbinato a un criterio XMLtoJSON nel flusso di risposta in uscita. Combinando i criteri in questo modo, un'API JSON può essere esposta per i servizi che supportano in modo nativo solo XML.

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

Per gli scenari in cui le API vengono utilizzate da diverse app client che possono richiedere JSON e XML, il formato della risposta può essere impostato in modo dinamico configurando i criteri da JSON a XML e da XML a JSON per l'esecuzione in modo condizionale. Consulta Variabili e condizioni di flusso per un'implementazione di questo scenario.

Schema

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per la gestione degli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e 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 oppure l'input (JSON) passato al criterio JSON al criterio XML non è valido o è in un formato non valido.
steps.jsontoxml.InCompatibleTypes 500 Questo errore si verifica se il tipo della variabile definita nell'elemento <Source> e nell'elemento <OutputVariable> non corrispondono. È obbligatorio che il tipo di variabili contenute all'interno dell'elemento <Source> e dell'elemento <OutputVariable> corrisponda. I tipi validi sono message e string.
steps.jsontoxml.InvalidSourceType 500 Questo errore si verifica se il tipo della variabile utilizzata per definire l'elemento <Source> non è valido. I tipi di variabile validi sono message e string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 Questo errore si verifica se la variabile specificata nell'elemento <Source> del criterio da JSON a 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 da JSON a XML è:
  • Fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio) oppure
  • 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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è 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