Règle JavaScript

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X.
En savoir plus

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, méthodes et propriétés le modèle d'objet JavaScript d'Apigee Edge ; 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.

À 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 implémenter un comportement personnalisé qui n'est couvert par aucune autre règle Edge 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 journalisation des messages 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 de journalisation des messages 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.

Pour connaître la version de JavaScript actuellement compatible, consultez la section Logiciels compatibles et versions compatibles.

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 réaliser 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 Edge, 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 appartient au service Modèle d'objet JavaScript. 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, Edge effectue un appel en 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 des informations sur les techniques de traitement des erreurs que vous pouvez utiliser dans un appel JavaScript, consultez cet article de la Communauté Apigee. 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 stratégie 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.

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

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

ND

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 Fichiers de 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. Voir Configuration de TLS de Edge au backend pour en savoir plus.

Remarques sur l'utilisation

Une règle JavaScript ne contient aucun code réel. À la place, une règle JavaScript référence une "ressource" JavaScript et définit l'étape du flux d'API où le script JavaScript s'exécute. Vous pouvez téléchargez votre script par le biais de l'éditeur de proxy de l'interface utilisateur de gestion, ou vous pouvez l'inclure dans le /resources/jsc des proxys d'API que vous développez localement.

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 Trace. 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 Trace, procédez comme suit :

  1. Ouvrez l'outil Trace et démarrez une session de suivi pour un proxy contenant votre règle JavaScript.
  2. Appelez le proxy.
  3. Dans l'outil Trace, 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 générer des informations de débogage dans l'outil Trace. Cette fonction est disponible directement via le modèle d'objet JavaScript. Pour en savoir plus, consultez la section "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 d'Apigee Edge.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés ainsi que les variables d'erreur qui sont définis par Edge 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. ND
steps.javascript.ScriptSecurityError 500 Une erreur de sécurité s'est produite lors de l'exécution du JavaScript. Pour en savoir plus, consultez la chaîne d'erreur. ND

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 ressource spécifiée dans l'élément <ResourceURL> ou <IncludeURL> de la règle JavaScript n'est pas valide, 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 avec cette erreur si <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. Ou, 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 Toutefois, si elle est déclarée, 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 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 :