Règle JSONtoXML

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône de la règle

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.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Tous les utilisateurs n'ont pas besoin de connaître les types de règles et d'environnements. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

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, consultez la section Convertir des données XML et JSON avec Apigee : ce qu'il faut savoir.

Convertir une requête

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

Cette configuration utilise un message de requête au format JSON comme source, puis crée un message au format XML qui est inséré dans la variable OutputVariable request. Apigee utilise automatiquement le contenu de cette variable comme message pour la prochaine étape du traitement.

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 :

Attribut Description Par défaut Présence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

 N/A Obligatoire
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également :

 faux Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

 vrai Facultatif
async

Cet attribut est obsolète.

 faux Obsolète

É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>
Par défaut

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Présence Facultatif
Type Chaîne

É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>
Par défaut requête ou réponse, déterminée par l'emplacement dans le flux de proxy de l'API où la règle est ajoutée.
Présence Facultatif
Type message

É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>
Par défaut requête ou réponse, déterminée par l'emplacement dans le flux de proxy de l'API où la règle est ajoutée.
Présence Cet élément est obligatoire lorsque la variable définie dans l'élément <Source> est de type chaîne.
Type message

<Options>/<OmitXmlDeclaration>

Permet d'omettre la ligne de déclaration XML dans le résultat. Une ligne de déclaration XML peut éventuellement apparaître en haut d'un document XML. Voici un exemple type : 

<?xml version="1.0" encoding="UTF-8"?>

Dans certains cas, il est important d'éviter d'inclure une telle ligne dans le résultat de cette règle. Un bon exemple est le cas où vous prévoyez d'intégrer le résultat de cette règle sous forme de fragment dans un document XML plus volumineux. Étant donné que la déclaration ne doit apparaître qu'une seule fois dans un document et uniquement en haut du document, il est important dans ce cas de supprimer la ligne de déclaration XML dans le fragment XML.

La valeur par défaut pour cette option est false, ce qui signifie que la règle inclut la ligne de déclaration XML dans le résultat. Le paramètre suivant configure la règle de façon à omettre la déclaration XML :

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Il n'existe aucun moyen de façonner ou d'affecter le contenu de la ligne de déclaration XML via la configuration de cette règle. La règle génère toujours du texte encodé au format UTF-8 et utilise toujours la version XML 1.0. La ligne de déclaration, si elle est incluse, reflétera ces caractéristiques.

Éléments <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

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>
Convertit l'objet JSON suivant : 
{"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 renvoyés et les variables d'erreur définies par Apigee lorsque cette règle 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.

Code d'erreur État HTTP Cause Corriger
steps.jsontoxml.ExecutionFailed 500 La charge utile d'entrée (JSON) est vide ou la valeur d'entrée (JSON) transmise par règle JSON vers XML n'est pas valide ou est incorrecte.
steps.jsontoxml.InCompatibleTypes 500 Cette erreur se produit si le type de la variable définie dans l'élément <Source> et l'élément <OutputVariable> ne sont pas identiques. Il est obligatoire que le type des variables contenues dans l'élément <Source> corresponde à celui de l'élément <OutputVariable>. Les types valides sont message et string.
steps.jsontoxml.InvalidSourceType 500 Cette erreur se produit si le type de la variable utilisée pour définir l'élément <Source> n'est pas valide. Les types de variables valides sont message et string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 Cette erreur se produit si la variable spécifiée dans l'élément <Source> de la stratégie JSON vers XML est de type chaîne et que l'élément <OutputVariable> n'est pas défini. L'élément <OutputVariable> est obligatoire lorsque la variable définie dans l'élément <Source> est de type chaîne.
steps.jsontoxml.SourceUnavailable 500 Cette erreur se produit si la variable message spécifiée dans l'élément <Source> de la stratégie JSON est XML :
  • hors du champ d'application (non disponible dans le flux spécifique où la règle est exécutée) ou
  • impossible à résoudre (non définie).

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.

Variables Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. jsontoxml.JSON-to-XML-1.failed = true

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