Règle XSLTransform

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

Consultez la documentation d'Apigee Edge.

icône de la règle

Événement

La règle XSLTransform applique des Transformations de langage de feuille de style extensible (XSLT) personnalisées aux messages XML, ce qui vous permet de les convertir de XML à un autre format, tel que HTML ou texte brut. Elle est souvent utilisée pour intégrer des applications compatibles avec XML, mais qui exigent des formats XML différents pour les mêmes données.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Entrées

La règle XSL utilise en entrée les paramètres suivants :

  • (Obligatoire) Nom d'une feuille de style XSLT qui contient un ensemble de règles de transformation stockées dans le proxy d'API sous /resources/xsl.
  • (Obligatoire) Fichier XML à transformer (généralement un message de requête ou de réponse).
  • (Facultatif) Nom d'une variable qui stocke le résultat en sortie.
  • (Facultatif) Paramètres correspondant aux paramètres de la feuille de style XSL.

Processeur d'analyse

Apigee s'appuie sur le processeur XSLT Saxon et est compatible avec XSLT 1.0 et 2.0.

Éléments XSL non compatibles

La règle XSL n'est pas compatible avec les éléments XSL suivants :

  • <xsl:include>
  • <xsl:import>

Exemples

Les exemples suivants illustrent un flux de transformation XSL :

Règle XSL -->

<XSL name="TransformXML">
  <ResourceURL>xsl://my_transform.xsl</ResourceURL>
  <Source>request</Source>
</XSL>

Règle XSL simple. Passez à l'exemple suivant pour voir la feuille de style XSLT référencée dans la règle (my_transform.xsl). L'élément <Source> est important. Par exemple, si le fichier XML que vous souhaitez transformer est présent dans la réponse, la transformation ne se produira que si vous définissez <Source> sur response (et que la règle est associée au flux de réponse). Cependant, dans le cas présent, le XML à transformer se trouve dans la requête.

Feuille de style XSLT -->

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output method="text"/>
  <xsl:variable name="newline">
    <xsl:text></xsl:text>
  </xsl:variable>
  <xsl:template match="/">
  <xsl:text>&lt;Life&gt;</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:text>Here are the odd-numbered items from the list:</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:for-each select="list/listitem">
      <xsl:if test="(position() mod 2) = 1">
        <xsl:number format="1. "/>
        <xsl:value-of select="."/>
        <xsl:value-of select="$newline"/>
      </xsl:if>
    </xsl:for-each>
  <xsl:text>&lt;/Life&gt;</xsl:text>
</xsl:template>
</xsl:stylesheet>

Feuille de style my_transform.xsl référencée dans la règle. Passez à l'exemple suivant pour voir un exemple de message XML entrant.

Message -->

<?xml version="1.0"?>
<list>
  <title>A few of my favorite albums</title>
  <listitem>A Love Supreme</listitem>
  <listitem>Beat Crazy</listitem>
  <listitem>Here Come the Warm Jets</listitem>
  <listitem>Kind of Blue</listitem>
  <listitem>London Calling</listitem>
  <listitem>Remain in Light</listitem>
  <listitem>The Joshua Tree</listitem>
  <listitem>The Indestructible Beat of Soweto</listitem>
</list>

Exemple de message dans la requête (indiqué dans l'élément <Source>request</Source> de la règle dans le premier exemple).

Message transformé

<Life>
Here are the odd-numbered items from the list:
1. A Love Supreme
3. Here Come the Warm Jets
5. London Calling
7. The Joshua Tree
</Life>

Le message transformé d'après la feuille de style XSLT de ces échantillons est appliqué au message XML.

Élément <XSL>

Définit une règle XSLTransform.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Objet complexe
Élément parent N/A
Éléments enfants <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

L'élément <XSL> possède les attributs suivants :

Attribut Description nécessaire Type
name Nom de la stratégie Les caractères que vous pouvez utiliser dans le nom se limitent à : A-Z0-9._\-$ %. L'interface utilisateur Apigee applique cependant des restrictions supplémentaires, telles que la suppression automatique des caractères qui ne sont pas alphanumériques. Obligatoire Chaîne

Référence d'élément enfant

Cette section décrit les éléments enfants de <XSL>.

<OutputVariable>

Variable qui stocke le résultat de la transformation. Vous devez définir cet élément en tant que variable personnalisée, puis utiliser cette variable.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Chaîne
Élément parent <XSL>
Éléments enfants Aucun

La valeur de <OutputVariable> ne peut pas être de type message ; autrement dit, ni message, request, ou response.

Pour remplacer le contenu du message par le résultat de la transformation, supprimez cet élément. Par exemple, si vous transformez un message en HTML, n'incluez pas cet élément.

<Parameters>

Ajout de la compatibilité avec l'élément <xsl:param> dans vos feuilles de style. Vous définissez chaque paramètre en tant qu'élément enfant <Parameter> de cet élément.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Tableau d'éléments <Parameter>
Élément parent <XSL>
Éléments enfants <Parameter>

L'élément <Parameters> possède les attributs suivants :

Attribut Description nécessaire Type
ignoreUnresolvedVariables Détermine si la règle ignore les erreurs de variables non résolues dans les instructions de script XSLT. La valeur par défaut est false, ce qui signifie que, par défaut, la règle génère des erreurs si elle rencontre des variables non résolues. Facultatif Booléen

<Parameter>

Définit un paramètre dans l'élément <Parameters>.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Objet complexe
Élément parent <Parameters>
Éléments enfants Aucun

L'élément <Parameter> possède les attributs suivants :

Attribute Requis ? Type Description
name Obligatoire Chaîne

Nom du paramètre. Apigee met en correspondance la valeur que vous définissez ici avec la valeur de l'attribut name sur un élément <xsl:param> dans la feuille de style.

Par exemple, si vous saisissez le nom uid, votre XSL peut ressembler à ceci : 

<xsl:param name="uid" select="''"/>
ref Facultatif Chaîne

Pointe vers une variable de contexte contenant la valeur du paramètre. Les valeurs des variables de contexte ref doivent être définies avant l'évaluation de cette règle.

Par exemple, si un paramètre uid doit obtenir sa valeur à partir d'une variable appelée authn.uid, l'élément <Parameter> ressemblerait à ceci :

<Parameter name="uid" ref="authn.uid"/>

Si vous utilisez cet attribut, n'utilisez pas l'attribut value.
value Facultatif Chaîne

Spécifie une valeur codée en dur pour le paramètre. Par exemple, si un paramètre nommé answer doit avoir la valeur 42, l'élément <Parameter> ressemblerait à ceci :

<Parameter name="answer" value="42"/>

Si vous utilisez cet attribut, n'utilisez pas l'attribut ref.

Le paramètre obtient sa valeur à partir de l'attribut ref ou à partir d'une valeur value explicite.

Pour obtenir un exemple et davantage d'informations, consultez la section Comment utiliser les paramètres facultatifs de la règle de transformation XSL ?

<ResourceURL>

Le fichier XSL qu'Apigee utilise pour transformer le message. La valeur de cet élément correspond au nom de la feuille de style XSL stockée dans le proxy d'API sous /resources/xsl.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <XSL>
Éléments enfants Aucun

Exemple :

<ResourceURL>xsl://SubscriberNumbers-Request.xsl</ResourceURL>

Pour en savoir plus, consultez la section Fichiers de ressources.

<Source>

Spécifie le message transformé. Cette valeur est généralement définie sur request ou response, selon que le message à transformer est entrant ou sortant.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Chaîne
Élément parent <XSL>
Éléments enfants Aucun

Le fichier XSL qui définit la transformation est défini par la <ResourceURL>.

  • Si la source est manquante, celui-ci est traité comme un message simple. Exemple : <Source>message</Source>
  • Si la variable source ne peut pas être résolue, ou si elle est résolue en un type qui n'est pas un message, l'étape de transformation échoue.

Informations de référence sur les erreurs

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.xsl.XSLSourceMessageNotAvailable 500 Cette erreur se produit si le message (ou la variable de chaîne) spécifié dans l'élément <Source> de la règle XSLTransform est hors du champ d'application (non disponible dans le flux spécifique où la règle est exécutée) ou s'il ne peut pas être résolu (non défini).
steps.xsl.XSLEvaluationFailed 500 Cette erreur se produit si la charge utile du fichier XML d'entrée est non disponible/mal formée, ou si la règle XSLTransform échoue/ne parvient pas à transformer le fichier XML d'entrée en fonction des règles de transformation fournies dans le fichier XSL. Plusieurs raisons peuvent expliquer l'échec de la règle XSLTransform. La raison de l'échec dans le message d'erreur fournira davantage d'informations sur la cause de l'échec.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur Cause Corriger
XSLEmptyResourceUrl Si l'élément <ResourceURL> de la règle XSLTransform est vide, le déploiement du proxy d'API échoue.
XSLInvalidResourceType Si le type de ressource spécifié dans l'élément <ResourceURL> de la règle XSLTransform n'est pas du type xsl, le déploiement du proxy d'API échoue.

Articles associés