Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Questo criterio converte i messaggi dal formato JSON (JavaScript Object Notation) a Extensible Markup Language (XML), che ti 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 XSL Transform con un foglio di stile personalizzato per eseguire la trasformazione necessaria.
Supponendo che l'intento sia convertire una richiesta in formato JSON in una richiesta in formato XML, il criterio verrebbe associato a un flusso di richiesta (ad esempio Richiesta / proxyEndpoint/PostFlow).
Samples
Per una discussione dettagliata sulla conversione tra JSON e XML, consulta http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.
Conversione di una richiesta
<JSONToXML name="jsontoxml"> <Source>request</Source> <OutputVariable>request</OutputVariable> </JSONToXML>
Questa configurazione utilizza come origine un messaggio di richiesta in formato JSON e poi crea un
messaggio in formato XML che viene compilato nella variabile di output request
. Edge 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 su 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 Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
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 |
Elemento <Source>
La variabile, la richiesta o la risposta, che contiene il messaggio JSON che vuoi convertire in XML.
Se <Source>
non viene definito, viene considerato 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 diverso da messaggio, il criterio genera un errore.
<Source>request</Source>
Predefinita | richiesta o risposta, determinata da dove il criterio viene aggiunto al flusso proxy API |
Presenza | Facoltativo |
Digitare | messaggio |
Elemento <OutputVariable>
Archivia l'output della conversione in formato JSON in XML. Di solito si tratta dello stesso valore dell'origine, ovvero di solito 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 considerato come
OutputVariable
. Ad esempio, se source
è request
,
OutputVariable
il valore predefinito sarà request
.
<OutputVariable>request</OutputVariable>
Predefinita | 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. |
Digitare | messaggio |
<Opzioni>/<OmitXmlDeclaration>
Specifica di omettere lo spazio dei nomi XML dall'output. Il valore predefinito è false
, il che significa di includere lo spazio dei nomi nell'output.
Ad esempio, la seguente impostazione configura il criterio in modo che ometta lo spazio dei nomi:
<OmitXmlDeclaration>true</OmitXmlDeclaration>
<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 una definizione di 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 utilizza 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 radice denominato, a XML.
Ad esempio, se il JSON viene visualizzato come:
{ "abc": "123", "efg": "234" }
Imposta <ObjectRootElementName> come segue:
<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é 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>
<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> elemento
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
, che significa che non viene eseguito il rientro.
Ad esempio, la seguente impostazione configura il criterio per applicare il rientro all'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, 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 valido che potrebbero causare problemi con un parser, questa impostazione sostituisce con la stringa tutti gli elementi JSON che producono file XML non validi. 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, è possibile esporre un'API JSON per i servizi che supportano solo XML in modo nativo.
Spesso è utile applicare il codice JSON predefinito (vuoto) al criterio XML e aggiungere iterativamente gli elementi di configurazione come richiesto.
Per scenari in cui le API vengono utilizzate da diverse app client che potrebbero 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 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 Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli 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
Nessuna.
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 da XML a JSON
- Trasformazione XSL: norme relative alla trasformazione XSL