Règle JavaScript

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

Consultez la documentation d' Apigee Edge.

La règle JavaScript vous permet d'ajouter du code JavaScript personnalisé qui s'exécute dans le contexte du flux de proxy d'API. Cette règle vous permet de mettre en œuvre un comportement personnalisé qui n'est pas couvert par les règles Apigee.

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. Vous pouvez obtenir, définir et supprimer des variables dans le contexte du flux de proxy, exécuter une logique personnalisée, gérer les exceptions, extraire des données de requêtes ou de réponses, et modifier de manière dynamique l'URL cible du backend. Vous pouvez également utiliser les fonctions de chiffrement de base disponibles dans le modèle d'objet.

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 à l'aide de 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 du code JavaScript à l'aide de l'éditeur de proxy de l'interface utilisateur Apigee.

Les fichiers source JavaScript doivent avoir une extension .js. Apigee est compatible avec JavaScript sur le moteur JavaScript Rhino 1.7.13.

Apigee ne recommande pas d'utiliser la règle JavaScript pour les cas suivants :

Journalisation. La règle MessageLogging est plus adaptée à la journalisation avec des plates-formes de journalisation tierces telles que Splunk, Sumo et Loggly. Cette règle améliore également les performances du proxy d'API en s'exécutant dans le PostClientFlow après que la réponse est renvoyée au client.
Remplacement des règles Apigee La règle JavaScript ne remplace pas les fonctionnalités des règles Apigee. Si les fonctionnalités dont vous avez besoin sont disponibles dans une règle Apigee, utilisez cette règle au lieu d'implémenter une solution JavaScript personnalisée. Il est possible que le code JavaScript personnalisé ne corresponde pas aux performances et à l'optimisation des règles Apigee.
Pour effectuer des appels système. Le modèle de sécurité n'autorise pas les appels système à partir de la règle JavaScript. Par exemple, les lectures ou écritures de système de fichiers internes, les informations utilisateur actuelles, les listes de processus ou l'utilisation du processeur/de la mémoire ne sont pas autorisées. Bien que certains appels puissent être fonctionnels, ils ne sont pas acceptés et peuvent être désactivés à tout moment. Pour assurer la compatibilité ascendante, évitez d'effectuer de tels appels dans votre code.

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.

Exemples

Réécriture de l'URL cible

Un cas d'utilisation courant consiste à extraire des données d'un corps de requête, à les stocker dans une variable de flux, puis à utiliser cette variable de flux ailleurs dans le flux de proxy. Par exemple, supposons qu'un utilisateur saisisse son nom dans un formulaire HTML et l'envoie. Pour extraire les données de formulaire et les ajouter dynamiquement à l'URL du service de backend, utilisez une règle JavaScript.

Remarque : Pour essayer cet exemple, créez un nouveau proxy dans l'éditeur de proxy. Lorsque vous créez le proxy, fournissez une URL de service de backend, par exemple http://www.example.com. Cet exemple réécrit dynamiquement l'URL du backend. Si vous devez créer un proxy, consultez le tutoriel de mise en route.

Dans l'interface utilisateur d'Apigee, ouvrez le proxy que vous avez créé dans l'éditeur de proxy.
Sélectionnez l'onglet Dévelop (Développer).
Dans le menu "New" (Nouveau), sélectionnez New Script (Nouveau script).
Dans la boîte de dialogue, sélectionnez JavaScript et nommez le script js-example.
Collez le code suivant dans l'éditeur de code et enregistrez le proxy. L'objet context 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'effectuer d'autres opérations. Cet objet fait partie du modèle d'objet JavaScript Apigee. La variable de flux target.url est une variable intégrée en lecture/écriture accessible dans le flux de requête cible. Lorsque vous définissez cette variable avec l'URL de l'API, Apigee appelle cette URL de backend. Cela réécrit l'URL cible d'origine, qui était l'URL que vous 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);
}
```
Dans le menu "New Policy" (Nouvelle règle), sélectionnez JavaScript.
Nommez la règle target-rewrite. Acceptez les paramètres par défaut et enregistrez la règle.
Une fois que vous avez sélectionné le PreFlow du point de terminaison du proxy dans le navigateur, la règle est ajoutée à ce flux.
Dans le Navigateur, sélectionnez PreFlow du point de terminaison cible.
Dans le Navigateur, faites glisser la règle JavaScript du côté "Requête" du point de terminaison cible dans l'éditeur de flux.
Enregistrer.
Remplacez le nom de votre organisation et le nom du proxy lorsque vous appelez l'API :

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

Examinons la définition XML pour la règle JavaScript utilisée dans cet exemple. L'élément <ResourceURL> spécifie le fichier source JavaScript à exécuter. Ce modèle s'applique à tout fichier source JavaScript : jsc://filename.js. Si votre code JavaScript nécessite des inclusions, utilisez un ou plusieurs éléments <IncludeURL>, comme décrit plus loin dans ce document.

<?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 sa valeur avec JavaScript au moment de l'exécution.

Utilisez l'attribut name de l'élément pour spécifier le nom permettant d'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 que JavaScript reçoit.

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é. 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é à l'aide de JavaScript. La fonction getVariable utilise ensuite le nom de variable récupéré 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);

Dans une règle JavaScript, l'accès à request.content.asJSON en mode lecture seule convertit les grands entiers en notation exponentielle dans le corps du message. Le message est 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>

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

Attribut	Description	Par défaut	Présence
languageVersion	Spécifie la version du langage JavaScript dans laquelle le code est écrit. Les valeurs incluent `VERSION_DEFAULT`, `VERSION_1_0`, `VERSION_1_1`, `VERSION_1_2`, `VERSION_1_3`, `VERSION_1_4`, `VERSION_1_5`, `VERSION_1_6`, `VERSION_1_7`, `VERSION_1_8` et `VERSION_ES6`.	VERSION_DEFAULT	Facultatif
timeLimit	Spécifie la durée maximale (en millisecondes) d'exécution d'un 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 sans frais, le temps d'exécution est limité à 200 ms.	N/A	Obligatoire

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
`name`	The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
`continueOnError`	Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
`enabled`	Set to `true` to enforce the policy. Set to `false` to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
`async`	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default

Default	N/A If you omit this element, the value of the policy's `name` attribute is used.
Presence	Optional
Type	String

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional

Type String

Élément <IncludeURL>

Spécifie un fichier de bibliothèque JavaScript à charger en tant que dépendance pour le fichier JavaScript principal spécifié avec l'élément <ResourceURL> ou <Source>. La règle évalue les scripts 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 à l'aide d'éléments <IncludeURL> supplémentaires.

Avertissement : Si vos fichiers JavaScript sont stockés au niveau du proxy ou de l'environnement, assurez-vous de les importer correctement avec cURL à l'aide de l'option -F ou en tant que pièce jointe via un client REST. Content-Type est multipart/form-data. Pour en savoir plus, consultez Gérer les ressources.

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

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

Élement <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	Présence
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écute 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 Navigateur de l'éditeur de proxy d'API). Vous pouvez également le stocker aux niveaux de l'organisation ou de l'environnement afin de le réutiliser sur plusieurs proxys d'API, comme décrit dans 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, la règle ignore `<ResourceURL>`.
Type :	Chaîne

Exemple

Consultez l'exemple dans la section Exemples.

Élément <Source>

Vous pouvez 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, la règle ignore `<ResourceURL>`.
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 utilisé pour configurer TLS pour un TargetEndpoint/TargetServer. Pour en savoir plus, consultez l'article Options de configuration de TLS.

Utiliser JavaScript pour gérer les erreurs

Vous pouvez utiliser la règle JavaScript pour gérer et renvoyer les erreurs. Pour en savoir plus sur ce sujet, consultez Comment corriger les erreurs à partir d'une règle JavaScript dans la communauté Apigee. Notez que les posts et commentaires de la communauté ne représentent pas nécessairement les bonnes pratiques recommandées par Apigee.

Déboguer le code de stratégie 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 Déboguer JavaScript avec des instructions print().

Pour afficher les instructions d'impression dans l'outil Debug :

Ouvrez l'outil Debug et démarrez une session de suivi pour un proxy contenant votre règle JavaScript.
Appelez le proxy.
Dans l'outil Debug, cliquez sur la règle JavaScript, puis sur l'onglet Propriétés pour afficher la propriété "stepExecution-stdout" qui indique la sortie de l'instruction print.
Vos instructions d'impression s'affichent dans ce panneau.

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 context. Exemple :

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

L'objet context 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.

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.

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 trouverez ces articles associés dans la Communauté Apigee :

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

Règle JavaScript Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Exemples

Réécriture de l'URL cible

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

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

Attributs <JavaScript>

<DisplayName> element

Élément <IncludeURL>

Élement <Property>

Attributs

Exemple

Élément <ResourceURL>

Exemple

Élément <Source>

Exemple

Élément <SSLInfo>

Utiliser JavaScript pour gérer les erreurs

Déboguer le code de stratégie JavaScript

Variables de flux

Informations de référence sur les erreurs

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Schéma

Articles associés

Articles de la Communauté Apigee

Règle JavaScript