Norme di JSONtoXML

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Questa policy converte i messaggi dal formato JSON (JavaScript Object Notation) al formato XML (Extensible Markup Language), offrendoti diverse opzioni per controllare la conversione dei messaggi.

La policy è particolarmente utile se vuoi trasformare i messaggi utilizzando XSL. Dopo aver convertito un payload JSON in XML, utilizza la policy Trasformazione XSL con un foglio di stile personalizzato per eseguire la trasformazione di cui hai bisogno.

Supponendo che l'intento sia convertire una richiesta in formato JSON in una richiesta in formato XML, la policy verrà collegata a un flusso di richieste (ad esempio, Request / ProxyEndpoint/ PostFlow).

Esempi

Per una discussione dettagliata sulla conversione tra JSON e XML, consulta l'articolo Problema di conversione dell'array JSON in array XML nell'oggetto di risposta.

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

Riferimento all'elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in questa policy.

<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 del criterio:

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Elemento <Source>

La variabile, richiesta o risposta, che contiene il messaggio JSON che vuoi convertire in XML.

Se <Source> non è definito, viene trattato come messaggio (che viene risolto in richiesta quando la policy è collegata a un flusso di richieste o in 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, la policy genera un errore.

<Source>request</Source>

Elemento <OutputVariable>

Memorizza l'output della conversione dal formato JSON al formato XML. In genere, il valore è lo stesso 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 HTTP Content-type 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 il source è request, allora OutputVariable viene impostato su request per impostazione predefinita.

<OutputVariable>request</OutputVariable>

Elemento <Options>/<OmitXmlDeclaration>

Specifica di omettere lo spazio dei nomi XML dall'output. Il valore predefinito è false , il che significa che lo spazio dei nomi viene incluso nell'output.

Ad esempio, la seguente impostazione configura la policy in modo da omettere lo spazio dei nomi:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Elementi <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

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

Ad esempio, le seguenti impostazioni:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

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

Elemento <Options>/<ObjectRootElementName>

<ObjectRootElementName> specifica il nome dell'elemento root quando converti da JSON, che non ha un elemento root denominato elemento, a XML.

Ad esempio, se il JSON viene visualizzato come:

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

E imposti <ObjectRootElementName> come:

<ObjectRootElementName>Root</ObjectRootElementName>

L'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é 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",

 }
}

nella 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 nomi di 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>

Elemento <Options>/<Indent>

Specifica di rientrare l'output XML. Il valore predefinito è false , il che significa che non viene eseguito il rientro.

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 attivato, 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
    }
}

in 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 null. Per impostazione predefinita, il valore è NULL.

Ad esempio, la seguente impostazione:

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

nel 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 tutti gli elementi JSON che producono XML non valido con la stringa. Ad esempio, la seguente impostazione:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Converte questo oggetto JSON

{
    "First%%%Name": "John"
}

in 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 le policy in questo modo, è possibile esporre un' API JSON per i servizi che supportano in modo nativo solo XML.

Spesso è utile applicare la policy da JSON a XML predefinita (vuota) 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 le policy da JSON a XML e da XML a JSON in modo che vengano eseguite in modo condizionale. Per un'implementazione di questo scenario, consulta 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 Edge 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.

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.

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

• Da XML a JSON: Da XML a JSON policy
• Trasformazione XSL: policy Trasformazione XSL