Règle JavaScript

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

Consultez la documentation d'Apigee Edge.

Quoi

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 à request.content.asJSON en lecture seule entraîne la conversion des grands entiers en notation exponentielle dans le corps du message. Le message sera alors 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	Presence
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.	N/A	Obligatoire

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

Attribut	Description	Par défaut	Presence
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	false	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.	true	Facultatif
async	Cet attribut est obsolète.	false	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.
Presence	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 :	Aucun
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 :	Aucun
Présence :	Facultatif
Type :	Chaîne

Attributs

Attribut	Description	Par défaut	Presence
nom	Spécifie le nom de la propriété.	N/A	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 :	Aucun
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 :	Aucun
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 :	Aucun
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 en savoir plus, consultez Déboguer JavaScript avec des instructions 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.javascript.ScriptExecutionFailed	500	The JavaScript policy can throw many different types of ScriptExecutionFailed errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	An error occurred in the JavaScript code. See the fault string for details.	N/A
steps.javascript.ScriptSecurityError	500	A security error occurred when the JavaScript executed. See the fault string for details.	N/A

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

Error name	Cause	Fix
InvalidResourceUrlFormat	If the format of the resource URL specified within the <ResourceURL> or the <IncludeURL> element of the JavaScript policy is invalid, then the deployment of the API proxy fails.
InvalidResourceUrlReference	If the <ResourceURL> or the <IncludeURL> elements refer to a JavaScript file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
WrongResourceType	This error occurs during deployment if the <ResourceURL> or the <IncludeURL> elements of the JavaScript policy refer to any resource type other than jsc (JavaScript file).
NoResourceURLOrSource	The deployment of the JavaScript policy can fail with this error if the <ResourceURL> element is not declared or if the resource URL is not defined within this element. <ResourceURL> element is a mandatory element. Or, The <IncludeURL> element is declared but the resource URL is not defined within this element. The <IncludeURL> element is optional but if declared, the resource URL must be specified within the <IncludeURL> element.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	javascript.JavaScript-1.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

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