Cette page a été traduite par l'API Cloud Translation.

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 erreurs, 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.

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.

Les fichiers source JavaScript doivent avoir une extension .js.

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

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);

Traiter les erreurs

Pour obtenir des exemples et une présentation des techniques de gestion des exceptions que vous pouvez utiliser dans un appel JavaScript, consultez 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 Google.

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

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

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

Remarques sur l'utilisation

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 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 de débogage, cliquez sur Sortie de toutes les transactions pour ouvrir le panneau de sortie.
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

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

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

Traiter les erreurs

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

Attributs <JavaScript>

Élément <DisplayName>

Élément <IncludeURL>

Élement <Property>

Attributs

Exemple

Élément <ResourceURL>

Exemple

Élément <Source>

Exemple

Élément <SSLInfo>

Remarques sur l'utilisation

Déboguer le code de la règle JavaScript

Variables de flux

Informations de référence sur les erreurs

Erreurs d'exécution

Erreurs de déploiement

Variables de panne

Exemple de réponse d'erreur

Exemple de règle de défaillance

Schéma

Articles associés

Articles de la Communauté Apigee

Règle JavaScript