Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
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. Non tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per 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>
<JSONToXML> attributi
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 Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
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 |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
<Source> elemento
La variabile, la richiesta o la risposta, che contiene il messaggio JSON in cui vuoi convertire XML.
Se <Source>
non viene definito, viene considerato come messaggio (e viene risolto
da richiedere quando il criterio è collegato a un flusso di richiesta o una risposta quando il criterio è collegato.
a un flusso di risposta).
Se la variabile di origine non può essere risolta o si risolve in un tipo non messaggio, il criterio genera un errore.
<Source>request</Source>
Predefinito | richiesta o risposta, determinata da dove il criterio viene aggiunto al flusso proxy API |
Presenza | Facoltativo |
Tipo | messaggio |
<OutputVariable> elemento
Archivia l'output della conversione in formato JSON in XML. Di solito corrisponde al valore cioè 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, determinata da dove il criterio viene aggiunto 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 della dichiarazione XML dall'output. Una riga di dichiarazione XML può appaiono facoltativamente 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 in un documento XML più grande. Perché la dichiarazione deve apparire una sola volta in un documento, e solo nella parte superiore, sarebbe importante che per sopprimere la riga della dichiarazione XML nel frammento XML.
Il valore predefinito di questa opzione è false
, il che significa
il criterio includerà la riga della 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 con codifica UTF-8 e genera sempre utilizza la versione XML 1.0 e la riga della dichiarazione, se inclusa, ne rifletterà la presenza.
<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 di uno spazio dei nomi
nel codice XML prodotto dal criterio. Ciò significa che il file JSON di origine deve
forniscono una proprietà che può essere mappata in uno spazio dei nomi previsto dall'applicazione
consuma il file XML risultante.
Ad esempio, le seguenti impostazioni:
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator>
indica che nel JSON di origine è presente 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>
<Options>/<ObjectRootElementName>
<ObjectRootElementName> specifica il nome dell'elemento radice quando esegui la conversione da JSON, che non ha un nome root in XML.
Ad esempio, se il codice JSON viene visualizzato come:
{ "abc": "123", "efg": "234" }
E imposti <ObjectRootElementName> come:
<ObjectRootElementName>Root</ObjectRootElementName>
Il codice XML risultante viene visualizzato come:
<Root> <abc>123</abc> <efg>234</efg> </Root>
<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elementi
<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 convertita nella seguente struttura XML:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<AttributePrefix>
converte la proprietà iniziando con il prefisso specificato
in attributi XML. In cui 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>
<Options>/<ArrayItemElementName> elemento
Converte un array JSON in un elenco di elementi XML con l'elemento principale e secondario specificati names.
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 di applicare il rientro all'output XML. Il valore predefinito è false
senza 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] }
Quindi 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>
<Options>/<TextNodeName> elemento
Converte una proprietà JSON in un nodo di testo XML con il nome specificato. Ad esempio, 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 viene specificato, viene generato il file XML utilizzando l'impostazione predefinita
per un nodo di testo:
<person> <firstName>John</firstName> <age>25</age> <lastName>Smith</lastName> </person>
<Options>/<NullValue> elemento
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>
Dove non viene specificato nessun valore (o un valore diverso da I_AM_NULL
) per il valore Null,
lo stesso payload viene convertito in:
<person>I_AM_NULL</person>
<Options>/< InvalidCharsSostituzione> elemento
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 un tipico scenario di mediazione, 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, se richiesto.
Per scenari in cui le API vengono utilizzate da diverse app dei clienti che potrebbero richiedere JSON e XML, il formato della risposta può essere impostato dinamicamente configurando da JSON a XML e XML a Criteri JSON da eseguire in modo condizionale. Consulta Variabili e condizioni di flusso per un'implementazione di questo scenario.
Schemi
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. | build |
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 . |
build |
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 . |
build |
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. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
Questo errore si verifica se la variabile message
specificata nell'elemento <Source> del criterio da JSON a XML è:
|
build |
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
- Da XML a JSON: criterio XMLtoJSON
- Trasformazione XSL: criterio XSLTransform