Norme di JSONtoXML

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

Cosa

Questo criterio converte i messaggi dal formato JSON (JavaScript Object Notation) al formato XML (Extensible Markup Language), 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 verrà collegato a un flusso di richiesta (ad esempio Request / ProxyEndpoint/PostFlow).

Esempi

Per una discussione dettagliata sulla conversione tra JSON e XML, vedi Problema di conversione da array JSON ad array XML nell'oggetto di risposta.

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

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

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 è impostata su text/xml;charset=UTF-8.

Se OutputVariable non è specificato, source viene trattato come OutputVariable. Ad esempio, se source è request, OutputVariable è impostato su request per impostazione predefinita.

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

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

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

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<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, il che significa che non viene applicata l'indentazione.

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>

{"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 del codice XML non valido che potrebbe causare problemi con un analizzatore sintattico, questa impostazione sostituisce qualsiasi elemento JSON che produce codice 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

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Nessuno.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

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

• XML to JSON: XML to JSON policy
• Trasformazione XSL: policy XSL Transform