Règle JSONtoXML

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Quoi

Cette règle convertit les messages du format JSON (JavaScript Object Notation) en un langage de balisage extensible (XML), offrant plusieurs options pour contrôler la conversion des messages.

Elle est particulièrement utile si vous souhaitez transformer des messages à l'aide de XSL. Après avoir converti une charge utile JSON en XML, utilisez la règle de transformation XSL avec une feuille de style personnalisée pour effectuer la transformation dont vous avez besoin.

En supposant que vous voulez convertir une requête au format JSON en requête au format XML, la règle sera associée à un flux de requête (par exemple, Request/ProxyEndpoint/PostFlow).

Exemples

Pour obtenir des informations détaillées sur la conversion entre JSON et XML, consultez la page suivante : http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.

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

Documentation de référence des éléments

Vous trouverez ci-dessous les éléments et les attributs que vous pouvez configurer sur cette règle.

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

Attributs <JSONToXML>

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Élément <Source>

La variable, requête ou réponse contenant le message JSON que vous souhaitez convertir en XML.

Si <Source> n'est pas défini, il est traité comme un message (qui renvoie une demande lorsque la règle est associée à un flux de requête ou une réponse lorsque la règle est associée à un flux de réponse).

Si la variable source ne peut pas être résolue ou est résolue en un type qui n'est pas un message, la règle génère une erreur.

<Source>request</Source>

Élément <OutputVariable>

Stocke la sortie de la conversion JSON au format XML. Il s'agit généralement de la même valeur que la source, étant donné qu'une requête JSON est généralement convertie en requête XML.

La charge utile du message JSON est analysée et convertie en XML, et l'en-tête HTTP Content-Type du message au format XML est défini sur text/xml;charset=UTF-8.

Si la variable OutputVariable n'est pas spécifiée, la source est traitée comme OutputVariable. Par exemple, si la source correspond à la requête (request), la valeur par défaut de OutputVariable est request.

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

Permet d'omettre l'espace de noms XML dans la sortie. La valeur par défaut est false, ce qui signifie que l'espace de noms est inclus dans la sortie.

Par exemple, le paramètre suivant configure la règle de façon à omettre l'espace de noms :

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

JSON n'est pas compatible avec les espaces de noms, mais les documents XML les nécessitent souvent. NamespaceBlockName vous permet de définir une propriété JSON qui sert de source d'espace de noms dans le fichier XML généré par la règle. (Cela signifie que le fichier JSON source doit fournir une propriété qui peut être mappée dans un espace de noms attendu par l'application qui utilise le fichier XML obtenu.)

Par exemple, les paramètres suivants :

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

indique qu'une propriété #namespaces existe dans le fichier source JSON contenant au moins un espace de noms désigné par défaut. Exemple :

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

se convertit en :

<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> spécifie le nom de l'élément racine lorsque vous effectuez une conversion à partir du format JSON, qui n'a pas d'élément racine nommé, vers XML.

Par exemple, si le fichier JSON apparaît comme suit :

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

Et vous définissez <ObjectRootElementName> comme suit :

<ObjectRootElementName>Root</ObjectRootElementName>

Le fichier XML obtenu se présente comme suit :

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

Éléments<Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

<AttributeBlockName> vous permet de spécifier à quel moment les éléments JSON sont convertis en attributs XML (et non en éléments XML).

Par exemple, le paramètre suivant convertit les propriétés d'un objet nommé #attrs en attributs XML :

<AttributeBlockName>#attrs</AttributeBlockName>

L'objet JSON suivant :

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },        
        "occupation" : "explorer",
    }
}

est converti au format XML suivant :

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<AttributePrefix> convertit la propriété, en commençant par le préfixe spécifié, en attributs XML. Où le préfixe d'attribut est défini sur @, par exemple :

<AttributePrefix>@</AttributePrefix>

Cela convertit l'objet JSON suivant :

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

à la structure XML suivante :

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

Élément <Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName>

Cela convertit un tableau JSON en une liste d'éléments XML avec les noms d'éléments parents et enfants spécifiés.

Par exemple, les paramètres suivants :

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

convertissent le tableau JSON suivant :

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

à la structure XML suivante :

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

<Options>/<Indent>

Indique de mettre en retrait la sortie XML. La valeur par défaut est false, ce qui signifie qu'elle ne doit pas être en retrait.

Par exemple, le paramètre suivant configure la règle pour mettre en retrait la sortie :

<Indent>true</Indent>

Si l'entrée JSON est au format suivant :

{"n": [1, 2, 3] }

La sortie sans retrait est la suivante :

<Array><n>1</n><n>2</n><n>3</n></Array>

Lorsque le retrait est activé, la sortie est la suivante :

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

Élément <Options>/<TextNodeName>

Convertit une propriété JSON en un nœud de texte XML avec le nom spécifié. Par exemple, le paramètre suivant :

<TextNodeName>age</TextNodeName>

convertit le code JSON ci-dessous :

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

à cette structure XML :

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

Si TextNodeName n'est pas spécifié, la structure XML est générée à l'aide du paramètre par défaut pour un nœud de texte :

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

Élément <Options>/<NullValue>

Indique une valeur nulle. La valeur par défaut est NULL.

Par exemple, le paramètre suivant :

<NullValue>I_AM_NULL</NullValue>

{"person" : "I_AM_NULL"}

à l'élément XML suivant :

<person></person>

Lorsqu'aucune valeur n'est spécifiée pour la valeur Null (ou la valeur est autre que I_AM_NULL), la même charge utile est convertie en :

<person>I_AM_NULL</person>

Élément <Options>/<InvalidCharsReplacement>

Pour faciliter la gestion des structures XML non valides susceptibles de provoquer des problèmes avec un analyseur, ce paramètre remplace tous les éléments JSON générant une structure XML non valide avec la chaîne. Par exemple, le paramètre suivant :

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Convertit l'objet JSON suivant :

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

à cette structure XML :

<First_Name>John<First_Name>

Remarques sur l'utilisation

Dans un scénario de médiation type, une règle JSONtoXML sur le flux de requêtes entrantes est souvent associée à une règle XMLtoJSON sur le flux de réponses sortantes. En combinant des règles de cette manière, une API JSON peut être exposée pour les services qui ne sont compatibles nativement qu'avec le format XML.

Il est souvent utile d'appliquer la règle JSON vers XML par défaut (vide) et d'ajouter les éléments de configuration nécessaires par itération.

Pour les scénarios dans lesquels les API sont consommées par diverses applications clientes pouvant nécessiter JSON ou XML, le format de réponse peut être défini de manière dynamique en configurant l'exécution conditionnelle de règles JSONtoXML et XMLtoJSON. Pour voir une mise en œuvre de ce scénario, consultez la page Variables de flux et conditions.

Schémas

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur qui sont renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Aucune

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

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

Exemple de règle de défaillance

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

Articles associés

• XML vers JSON : règle XML vers JSON
• Transformation XSL : règle XSL