Norme di JSONtoXML

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio JSONtoXML converte i messaggi dal formato JavaScript Object Notation (JSON) al formato Extensible Markup Language (XML), 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.

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

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

Esempi

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

Convertire una richiesta

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

Questa configurazione prende come origine un messaggio di richiesta in formato JSON e poi crea un messaggio in formato XML che viene inserito nella variabile di output request. 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 trattato 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 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 viene 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 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. Una riga di dichiarazione XML può facoltativamente apparire 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 sarebbe 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 per 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. 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>

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 da JSON a XML nel flusso di richieste in entrata viene spesso abbinata a una policy da XML a JSON 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 il criterio JSON to XML predefinito (vuoto) 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 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.jsontoxml.ExecutionFailed 500 The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed.
steps.jsontoxml.InCompatibleTypes 500 This error occurs if the type of the variable defined in the <Source> element and the <OutputVariable> element are not the same. It is mandatory that the type of the variables contained within the <Source> element and the <OutputVariable> element matches. The valid types are message and string.
steps.jsontoxml.InvalidSourceType 500 This error occurs if the type of the variable used to define the <Source> element is invalid. The valid types of variable are message and string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 This error occurs if the variable specified in the <Source> element of the JSON to XML Policy is of type string and the <OutputVariable> element is not defined. The <OutputVariable> element is mandatory when the variable defined in the <Source> element is of type string.
steps.jsontoxml.SourceUnavailable 500 This error occurs if the message variable specified in the <Source> element of the JSON to XML policy is either:
  • Out of scope (not available in the specific flow where the policy is being executed) or
  • Can't be resolved (is not defined)

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. jsontoxml.JSON-to-XML-1.failed = true

Example error response

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

Example fault rule

<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