Règle JavaScript

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

Consultez la documentation d'Apigee Edge.

icône de la règle

É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

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 ?

  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.


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.

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 :

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.

<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

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.

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

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

Articles de la Communauté Apigee

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