Règle JavaScript

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

Consultez la documentation d'Apigee Edge.

Événement

Cette règle vous permet d'ajouter du code JavaScript personnalisé qui s'exécute dans le contexte d'un flux de proxy d'API. Dans votre code JavaScript personnalisé, vous pouvez utiliser les objets, les méthodes et les propriétés du modèle d'objet JavaScript Apigee. Le modèle d'objet vous permet d'obtenir, de définir et de supprimer des variables dans le contexte du flux de proxy. Vous pouvez également utiliser les fonctions de chiffrement de base fournies avec le modèle d'objet.

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.

À propos

La règle JavaScript présente de nombreux cas d'utilisation. Par exemple, vous pouvez obtenir et définir des variables de flux, exécuter une logique personnalisée et procéder à la gestion des erreurs, extraire des données de requêtes ou de réponses, modifier de manière dynamique l'URL cible du backend, etc. Cette règle vous permet de mettre en œuvre un comportement personnalisé qui n'est couvert par aucune autre règle Apigee standard. En fait, vous pouvez utiliser une règle JavaScript pour obtenir à l'identique la plupart des comportements mis en œuvre par d'autres règles, telles que AssignMessage et ExtractVariable.

La journalisation est un cas d'utilisation non recommandé pour la règle JavaScript. La règle de MessageLogging est bien plus adaptée à la journalisation sur des plates-formes de journalisation tierces telles que Splunk, Sumo et Loggly. Vous améliorez les performances du proxy d'API en exécutant la règle MessageLogging dans PostClientFlow, qui s'exécute une fois la réponse renvoyée au client.

La règle JavaScript vous permet de spécifier un fichier source JavaScript à exécuter ou d'inclure du code JavaScript directement dans la configuration de la règle avec l'élément <Source>. Dans les deux cas, le code JavaScript s'exécute lorsque l'étape à laquelle la règle est associée s'exécute. Pour l'option de fichier source, le code source est toujours stocké dans un emplacement standard dans le groupe de proxys : apiproxy/resources/jsc. Vous pouvez également stocker le code source dans un fichier de ressources au niveau de l'environnement ou de l'organisation. Pour obtenir des instructions, consultez la section Fichiers de ressources. Vous pouvez également importer votre code JavaScript via l'éditeur de proxy de l'interface utilisateur Apigee.

Les fichiers source JavaScript doivent toujours avoir une extension .js.

Apigee est compatible avec JavaScript sur le moteur JavaScript Rhino 1.7.13.

Vidéo

Remarque : La vidéo suivante montre l'éditeur de proxy classique dans l'interface utilisateur d'Apigee. Apigee intègre une nouvelle version de l'éditeur de proxys, dont la conception est différente de celle de la version classique présentée dans la vidéo.

Regardez une courte vidéo pour apprendre à créer une extension de règle personnalisée à l'aide de la règle JavaScript.

Exemples

Réécriture de l'URL cible

Voici un cas d'utilisation courant : extraire des données à partir d'un corps de requête, les stocker dans une variable de flux et utiliser cette variable de flux ailleurs dans le flux de proxy. Imaginons que vous avez une application dans laquelle l'utilisateur saisit son nom dans un formulaire HTML et l'envoie. Vous souhaitez que le proxy d'API extrait les données de formulaire et les ajoute dynamiquement à l'URL utilisée pour appeler le service de backend. Comment procéder dans une règle JavaScript ?

Remarque : Si vous souhaitez tenter de suivre cet exemple, nous supposons que vous avez créé un nouveau proxy dans l'éditeur de proxy. Lors de sa création, attribuez-lui simplement une URL de service de backend : http://www.example.com. Pour cet exemple, nous allons réécrire l'URL de backend de manière dynamique. Si vous ne savez pas comment créer un proxy, reportez-vous au tutoriel de mise en route.

1. Dans l'interface utilisateur d'Apigee, ouvrez le proxy que vous avez créé dans l'éditeur de proxy.
2. Sélectionnez l'onglet Dévelop (Développer).
3. Dans le menu "New" (Nouveau), sélectionnez New Script (Nouveau script).
4. Dans la boîte de dialogue, sélectionnez JavaScript et attribuez un nom au script, tel que js-example.
5. Collez le code suivant dans l'éditeur de code et enregistrez le proxy. L'élément important à noter est l'objet context. Cet objet est disponible pour le code JavaScript n'importe où dans le flux de proxy. Il permet d'obtenir des constantes spécifiques au flux, d'appeler des méthodes get/set utiles et d'autres opérations. Cette partie de l'objet est basée sur le modèle d'objet JavaScript d'Apigee. Notez également que la variable de flux target.url est une variable intégrée en lecture/écriture accessible depuis le flux de requête cible. Lorsque nous définissons cette variable avec l'URL de l'API, Apigee effectue son appel de backend vers cette URL. Nous avons essentiellement réécrit l'URL cible d'origine, telle que vous l'avez spécifiée lors de la création du proxy (par exemple, http://www.example.com).
   
   

   if (context.flow=="PROXY_REQ_FLOW") {
        var username = context.getVariable("request.formparam.user");
        context.setVariable("info.username", username);
   }
   
   if (context.flow=="TARGET_REQ_FLOW") {
        context.setVariable("request.verb", "GET");
        var name = context.getVariable("info.username");
        var url = "http://mocktarget.apigee.net/"
        context.setVariable("target.url", url + "?user=" + name);
   }
6. Dans le menu "New Policy" (Nouvelle règle), sélectionnez JavaScript.
7. Attribuez un nom à la règle, par exemple target-rewrite. Acceptez les paramètres par défaut et enregistrez la règle.
8. Si vous sélectionnez le Preflow du point de terminaison du proxy dans le navigateur, vous verrez que la règle a été ajoutée à ce flux.
9. Dans le navigateur, sélectionnez l'icône Target Endpoint PreFlow (PreFlow du point de terminaison cible).
10. Dans le navigateur, faites glisser la règle JavaScript du côté "Requête" du point de terminaison cible dans l'éditeur de flux.
11. Enregistrer.
12. Appelez l'API comme suit, en remplaçant le nom de votre organisation et le nom de proxy par les informations appropriées :

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Enfin, examinons la définition XML pour la règle JavaScript utilisée dans cet exemple. Il est important de noter que l'élément <ResourceURL> est utilisé pour spécifier le fichier source JavaScript à exécuter. Ce même modèle est utilisé pour tout fichier source JavaScript : jsc://filename.js. Si votre code JavaScript nécessite des inclusions, vous pouvez utiliser un ou plusieurs éléments <IncludeURL> pour réaliser cette opération, comme décrit plus loin dans cette documentation.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

Récupérer la valeur de propriété à partir de JavaScript

Vous pouvez ajouter un élément <Property> dans la configuration, puis récupérer la valeur de l'élément avec JavaScript au moment de l'exécution.

Utilisez l'attribut name de l'élément pour spécifier le nom avec lequel accéder à la propriété à partir du code JavaScript. La valeur de l'élément <Property> (la valeur entre les balises d'ouverture et de fermeture) correspond à la valeur littérale qui sera reçue par le JavaScript.

En JavaScript, vous récupérez la valeur de la propriété de la règle en y accédant en tant que propriété de l'objet Properties, comme suit :

• Configurez la propriété. Ici, la valeur de la propriété est le nom de la variable response.status.code.

  <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite">
      <DisplayName>JavascriptURLRewrite</DisplayName>
      <Properties>
          <Property name="source">response.status.code</Property>
      </Properties>
      <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL>
  </Javascript>

• Récupérez la propriété avec JavaScript. Ici, la valeur récupérée (un nom de variable) est ensuite utilisée par la fonction getVariable pour extraire la valeur de la variable.

  var responseCode = properties.source; // Returns "response.status.code"
  var value = context.getVariable(responseCode); // Get the value of response.status.code
  context.setVariable("response.header.x-target-response-code", value);

Traiter les erreurs

Pour obtenir des exemples et une présentation des techniques de traitement des erreurs que vous pouvez utiliser dans un appel JavaScript, consultez la section Comment corriger les erreurs à partir d'une règle JavaScript. Les suggestions proposées dans la Communauté Apigee sont données uniquement à titre d'informations et ne représentent pas nécessairement les bonnes pratiques recommandées par Apigee.

Dans une règle JavaScript, l'accès de request.content.asJSON en lecture seule entraîne la conversion des entiers volumineux en notation exponentielle dans le corps du message. Par conséquent, le message sera remplacé par les valeurs converties.

---

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

La documentation de référence des éléments décrit les éléments et les attributs de la règle JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false"
        continueOnError="false" enabled="true" timeLimit="200"
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>
</Javascript>

Attributs <JavaScript>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Les attributs suivants sont spécifiques à cette règle.

Attribut	Description	Par défaut	Présence
timeLimit	Spécifie la durée maximale (en millisecondes) autorisée pour l'exécution par le script. Par exemple, si une limite de 200 ms est dépassée, la règle génère l'erreur suivante : Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. Remarque : Pour les comptes d'essai gratuit, le temps d'exécution est limité à 200 ms.	ND	Obligatoire

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 : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	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 <IncludeURL>

Spécifie un fichier de bibliothèque JavaScript à charger en tant que dépendance au fichier JavaScript principal spécifié avec l'élément <ResourceURL> ou <Source>. Les scripts seront évalués dans l'ordre dans lequel ils sont répertoriés dans la règle. Votre code peut utiliser les objets, les méthodes et les propriétés du modèle d'objet JavaScript.

Incluez plusieurs ressources de dépendance JavaScript avec des éléments <IncludeURL> supplémentaires.

Avertissement : Si vos fichiers JavaScript sont stockés au niveau de l'organisation ou de l'environnement, vérifiez qu'ils ont été importés correctement avec cURL à l'aide de l'option -F ou en tant que pièce jointe via un client REST. La valeur de Content-Type est multipart/form-data. Pour en savoir plus, consultez la page Gérer les ressources.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Valeur par défaut :	None
Présence :	Facultatif
Type :	Chaîne

Exemple

Consultez l'exemple de base dans la section Exemples.

Élément <Property>

Spécifie une propriété à laquelle vous pouvez accéder à partir du code JavaScript lors de l'exécution.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Valeur par défaut :	None
Présence :	Facultatif
Type :	Chaîne

Attributs

Attribut	Description	Par défaut	Présence
nom	Spécifie le nom de la propriété.	ND	Obligatoire.

Exemple

Consultez l'exemple dans la section Exemples.

Élément <ResourceURL>

Spécifie le fichier JavaScript principal qui s'exécutera dans le flux de l'API. Vous pouvez stocker ce fichier au niveau du proxy d'API (sous /apiproxy/resources/jsc dans le groupe de proxys d'API ou dans la section "Scripts" du volet de navigation de l'éditeur de proxy d'API), ou aux niveaux de l'organisation ou de l'environnement afin de le réutiliser sur plusieurs proxys d'API, comme décrit dans la section Gérer les ressources. Votre code peut utiliser les objets, les méthodes et les propriétés du modèle d'objet JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Valeur par défaut :	None
Présence :	<ResourceURL> ou <Source> est obligatoire. Si les éléments <ResourceURL> et <Source> sont tous deux présents, <ResourceURL> est ignoré.
Type :	Chaîne

Exemple

Consultez l'exemple de base dans la section Exemples.

Élément <Source>

Permet d'insérer du code JavaScript directement dans la configuration XML de la règle. Le code JavaScript inséré s'exécute lorsque la règle s'exécute dans le flux de l'API.

Valeur par défaut :	None
Présence :	<ResourceURL> ou <Source> est obligatoire. Si les éléments <ResourceURL> et <Source> sont tous deux présents, <ResourceURL> est ignoré.
Type :	Chaîne

Exemple

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

Élément <SSLInfo>

Spécifie les propriétés utilisées pour configurer TLS pour toutes les instances de client HTTP créées par la règle JavaScript.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Valeur par défaut :	None
Présence :	Facultatif
Type :	Chaîne

Le processus de configuration TLS pour un client HTTP est le même que celui que vous utilisez pour configurer TLS pour un TargetEndpoint/TargetServer. Pour en savoir plus, consultez l'article Options de configuration de TLS.

Remarques sur l'utilisation

Avertissement : Les appels système ne sont pas autorisés par le modèle de sécurité. Exemple : les systèmes de fichiers internes lisent ou écrivent, ou obtiennent des informations utilisateur actuelles, la liste des processus ou l'utilisation du processeur/de la mémoire. Bien que certains de ces appels puissent être fonctionnels, ils ne sont pas acceptés et sont susceptibles d'être désactivés à tout moment. Pour assurer la compatibilité ascendante, vous devez éviter d'effectuer de tels appels dans votre code.

Déboguer le code de la règle JavaScript

Utilisez la fonction print() pour générer des informations de débogage dans le panneau de sortie des transactions de l'outil Debug. Pour obtenir plus d'informations et des exemples, consultez la section "Déboguer avec des instructions print() JavaScript".

Pour afficher les instructions d'impression dans Debug, procédez comme suit :

1. Ouvrez l'outil Debug et démarrez une session de suivi pour un proxy contenant votre règle JavaScript.
2. Appelez le proxy.
3. Dans l'outil Debug, cliquez sur Sortie de toutes les transactions pour ouvrir le panneau de sortie.

   

4. Vos instructions d'impression s'affichent dans ce panneau.

Vous pouvez utiliser la fonction print() pour envoyer les informations de débogage à l'outil Debug. Cette fonction est disponible directement via le modèle d'objet JavaScript. Pour plus d'informations, consultez la section Déboguer JavaScript avec les fonctions print().

Variables de flux

Cette règle ne remplit aucune variable par défaut. Toutefois, vous pouvez définir (et obtenir) des variables de flux dans votre code JavaScript en appelant des méthodes sur l'objet de contexte. Un modèle type se présente comme suit :

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

L'objet de contexte fait partie du modèle d'objet JavaScript Apigee.

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.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Code d'erreur	État HTTP	Cause	Corriger
steps.javascript.ScriptExecutionFailed	500	La règle JavaScript peut générer de nombreux types d'erreurs ScriptExecutionFailed. Les types d'erreurs fréquemment constatées incluent RangeError, ReferenceError, SyntaxError, TypeError et URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Une erreur s'est produite dans le code JavaScript. Pour en savoir plus, consultez la chaîne d'erreur.	Non disponible
steps.javascript.ScriptSecurityError	500	Une erreur de sécurité s'est produite lors de l'exécution de JavaScript. Pour en savoir plus, consultez la chaîne d'erreur.	Non disponible

Erreurs de déploiement

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

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur à côté de la description de la cause de l'erreur pour accéder à la page de dépannage.

Nom de l'erreur	Cause	Corriger
InvalidResourceUrlFormat	Si le format de l'URL de la ressource spécifiée dans l'élément <ResourceURL> ou <IncludeURL> de la règle JavaScript n'est pas valide, alors le déploiement du proxy d'API échoue.
InvalidResourceUrlReference	Si les éléments <ResourceURL> ou <IncludeURL> font référence à un fichier JavaScript qui n'existe pas, alors le déploiement du proxy d'API échoue. Le fichier source référencé doit exister au niveau du proxy d'API, de l'environnement ou de l'organisation.
WrongResourceType	Cette erreur se produit lors du déploiement si les éléments <ResourceURL> et <IncludeURL> de la règle JavaScript font référence à un type de ressource autre que jsc (fichier JavaScript).
NoResourceURLOrSource	Le déploiement de la règle JavaScript peut échouer et renvoyer cette erreur si l'élément <ResourceURL> n'est pas déclaré ou si l'URL de la ressource n'est pas définie dans cet élément. L'élément <ResourceURL> est obligatoire. L'élément <IncludeURL> est déclaré, mais l'URL de la ressource n'est pas définie dans cet élément. L'élément <IncludeURL> est facultatif, mais s'il est déclaré, l'URL de la ressource doit être spécifiée dans l'élément <IncludeURL>.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. 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 "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	javascript.JavaScript-1.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Exemple de règle de défaillance

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

Schéma

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Articles associés

• Modèle d'objet JavaScript

Articles de la Communauté Apigee

Vous pouvez trouver ces articles associés sur la Communauté Apigee :

• Comment gérer les en-têtes à multiples valeurs en JavaScript ?