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

Programmer des proxys d'API avec JavaScript

Vous consultez la documentation sur Apigee Edge.
Consultez la documentation sur Apigee X.

Dans cette rubrique, vous allez apprendre à utiliser JavaScript pour ajouter dynamiquement des en-têtes HTTP à un message de réponse. Vous allez également apprendre à analyser une réponse JSON et renvoyer un sous-ensemble de ses propriétés à l'application à l'origine de la demande.

Télécharger et tester l'exemple de code

À propos de cet exemple de livre de recettes

Cet exemple de livre de recettes illustre un modèle de proxy d'API dans lequel vous implémentez le comportement de l'API en JavaScript. Les exemples JavaScript sont conçus pour vous montrer comment utiliser des variables simples et le contenu des messages. Un exemple vous montre comment obtenir (get) et définir des variables. Le deuxième exemple vous montre comment analyser JSON et créer un message à partir du résultat.

Deux exemples de code JavaScript se trouvent dans le proxy d'API:

setHeaders.js: ce JavaScript obtient les valeurs de quelques variables définies lorsqu'un proxy d'API est appelé. Le code JavaScript ajoute ces variables au message de réponse afin que vous puissiez voir leurs valeurs pour chaque requête que vous effectuez.
minimize.js: ce code JavaScript vous montre comment utiliser le contenu des messages. L'objectif de cet exemple est qu'un service renvoie souvent plus de données que nécessaire. Ainsi, le code JavaScript analyse le message de réponse, extrait quelques propriétés intéressantes, puis les utilise pour créer le contenu du message de réponse.

Le code de setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Le code de minimize.js:

//Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

//Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
//Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Vous pouvez accéder aux variables de flux en JavaScript via l'objet de contexte. Cet objet fait partie du modèle d'objet Edge JavaScript. Pour en savoir plus sur le modèle d'objet, consultez Modèle d'objet JavaScript.

Avant de commencer

Avant d'explorer cet exemple de livre de recettes, vous devez également connaître les concepts fondamentaux suivants:

En quoi consistent les règles et comment les associer aux proxys. Pour en savoir plus sur les règles, consultez Qu'est-ce qu'une règle ?
Structure d'un flux de proxy, comme expliqué dans la section Configurer des flux. Les flux vous permettent de spécifier la séquence dans laquelle les règles sont exécutées par un proxy d'API. Dans cet exemple, plusieurs règles sont créées et ajoutées à un flux de proxy d'API.
Comment un projet de proxy d'API est organisé sur votre système de fichiers, comme expliqué dans la documentation de référence sur la configuration du proxy d'API.
Connaissance pratique de XML, JSON et JavaScript. Dans cet exemple, vous allez créer le proxy d'API et ses règles avec des fichiers XML situés sur le système de fichiers.

Si vous avez téléchargé l'exemple de code, vous pouvez retrouver tous les fichiers abordés dans cette rubrique dans le dossier d'exemples javascript-cookbook. Les sections suivantes décrivent l'exemple de code en détail.

Comprendre le flux de proxy

Pour que JavaScript s'exécute dans un proxy d'API, vous devez l'associer à un flux à l'aide d'un rattachement de règle appelé "étape". Une règle de type JavaScript (majuscules dans les notes) contient simplement une référence au nom d'un fichier JavaScript. Vous devez pointer la stratégie vers un fichier JavaScript à l'aide de l'élément ResourceURL.

Par exemple, la règle suivante fait référence au fichier JavaScript appelé setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Bonne pratique:Utilisez toujours l'extension .js pour les ressources JavaScript.

Vous pouvez associer cette stratégie à un flux de proxy d'API comme vous le feriez pour tout autre type de règle. En associant la stratégie au flux de proxy d'API, vous indiquez où le JavaScript doit être exécuté. Cela vous permet d'exécuter JavaScript qui interagit avec les messages de requête ou de réponse au fil de leur "diffusion" via le proxy d'API. Dans cet exemple, les deux JavaScripts s'exécutent dans le flux de réponse, car les stratégies effectuent deux opérations: définir des en-têtes HTTP sur le message de réponse et "réduire" le message de réponse renvoyé par Apigee Edge à l'application à l'origine de la demande.

Si vous ouvrez cette configuration de flux dans l'interface de gestion, la configuration de flux ci-dessous s'affichera.

Sélectionnez Points de terminaison du proxy > par défaut > PostFlow dans le volet Navigateur.

La configuration XML correspondant à ProxyEndpoint nommé "default" est présentée ci-dessous.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Voici un résumé des éléments du flux.

<Request> : l'élément <Request> comprend plusieurs éléments <Step>. Chaque étape appelle l'une des règles que vous créez dans la suite de cette section. Ces stratégies associent un code JavaScript au flux proxy de l'API. L'emplacement du rattachement de stratégie détermine le moment où le code JavaScript s'exécute.
<Response> : l'élément <Response> inclut également <Steps>. Ces étapes appellent également des stratégies responsables du traitement de la réponse finale de la cible (qui, dans cet exemple, est la cible de service fictive d'Apigee, notez le paramètre HTTPTargetConnection sous /apiproxy/targets/default.xml).
<HTTPProxyConnection> : spécifie l'hôte et le chemin d'URI qui définissent l'adresse réseau que les applications appellent pour utiliser cette API.
<RouteRule> : cet élément spécifie la configuration TargetEndpoint appelée par le ProxyEndpoint.

Ajouter du code JavaScript à un proxy

Les éléments JavaScript (comme les scripts Python, les fichiers JAR Java, les fichiers WebGL, etc.) sont stockés en tant que ressources. Lorsque vous commencez à utiliser JavaScript, il est plus facile de stocker vos fichiers JavaScript dans le proxy d'API. À mesure que vous avancez, JavaScript doit être aussi générique et réutilisable que possible, puis stocké au niveau de l'environnement ou de l'organisation. Cela vous évite d'avoir à stocker les mêmes fichiers JavaScript dans plusieurs proxys d'API, ce qui peut rapidement devenir ingérable.

Pour savoir comment stocker des ressources au niveau de l'organisation et de l'environnement, consultez Fichiers de ressources.

Essayer

Pour savoir comment déployer et appeler le proxy, consultez le fichier README de JavaScript.

Importer et déployer le proxy d'API

Une fois les modifications effectuées, vous pouvez enregistrer le proxy d'API dans l'outil de création de proxy d'API dans l'UI de gestion.

Vous pouvez également exécuter la commande suivante dans le répertoire /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Tester JavaScript

Exécutez la commande suivante dans le répertoire /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

L'indicateur curl -v est utilisé dans le script shell pour afficher les en-têtes HTTP du message de réponse modifié par le JavaScript.

Vous pouvez envoyer une demande directement comme suit:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Si JavaScript s'exécute correctement, vous obtiendrez une réponse semblable à celle-ci:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Vous pouvez maintenant modifier le code JavaScript pour essayer de nouvelles choses, redéployer le proxy d'API et vérifier les résultats en envoyant la même requête. Assurez-vous toujours de déployer le proxy d'API contenant votre JavaScript pour que vos modifications soient prises en compte.

Erreurs de script

Vous verrez inévitablement des erreurs lorsque vous écrivez JavaScript. Le format des erreurs JavaScript qui sont émises par un proxy d'API est illustré ci-dessous.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Quand utiliser JavaScript ?

Sur Apigee Edge, il existe généralement plusieurs façons de mettre en œuvre des fonctionnalités spécifiques. Utilisez des règles prêtes à l'emploi lorsque cela est possible, et évitez de coder toute la logique de votre proxy d'API en JavaScript. Bien qu'Apigee Edge utilise le code JavaScript compilé pour améliorer les performances, il est peu probable que JavaScript fonctionne aussi bien que les règles. JavaScript peut être plus difficile à gérer et à déboguer. Réservez le code JavaScript à des fonctionnalités qui répondent à vos besoins.

Si les performances concernent les fonctionnalités personnalisées, utilisez Java dans la mesure du possible.

Résumé

Dans cette section, vous avez découvert comment inclure JavaScript dans une configuration de proxy d'API pour implémenter un comportement personnalisé. Le comportement personnalisé mis en œuvre par les exemples montre comment obtenir et variables, et comment analyser JSON et construire des messages de réponse personnalisés.