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

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

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

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.

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

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

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

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>

Attributs

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>

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.

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>

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.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

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.

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

• Modèle d'objet JavaScript
• Pour obtenir des instructions, des exemples de règles et des exemples JavaScript, consultez la section Programmer des proxys d'API avec 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 ?