Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Programmer des proxys d'API avec JavaScript

Vous consultez la documentation Apigee Edge.
Accédez à la documentation**Apigee X**. info

Dans cette section, vous apprendrez à utiliser JavaScript pour ajouter dynamiquement des en-têtes HTTP à un message de réponse, à analyser une réponse JSON et à renvoyer un sous-ensemble de ses propriétés à l' application qui envoie la requête.

Télécharger et essayer 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 et définir des variables. Le deuxième exemple vous montre comment analyser du code JSON et créer un message à partir du résultat.

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

setHeaders.js : ce code JavaScript obtient les valeurs de quelques variables définies lorsqu'un proxy d'API est appelé. Il 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'idée derrière 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.

Code pour 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"));

Code pour 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 de le modèle d'objet JavaScript Edge. Pour en savoir plus sur le modèle d'objet, consultez la section 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 :

Que sont les règles et comment les associer à des proxys. Pour une bonne introduction aux règles, consultez Qu'est-ce qu'une règle ?.
La structure d'un flux de proxy, comme expliqué dans 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.
Une connaissance pratique de XML, JSON et JavaScript. Dans cet exemple, vous créez le proxy d'API et ses règles avec des fichiers XML qui résident sur le système de fichiers.

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

Comprendre le flux du proxy

Pour exécuter du code JavaScript dans un proxy d'API, vous devez l'associer à un flux à l'aide d'une association de règle appelée "étape". Une règle de type Javascript (notez la majuscule) contient simplement une référence au nom d'un fichier JavaScript. Vous pointez la règle 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 règle à un flux de proxy d'API comme vous le feriez pour tout autre type de règle. En associant la règle au flux de proxy d'API, vous indiquez où le code JavaScript doit être exécuté. Cela vous permet d'exécuter du code JavaScript qui interagit avec les messages de requête ou de réponse lorsque ces messages 'circulent' dans le proxy d'API. Dans cet exemple, les deux codes JavaScript s'exécutent dans le flux de réponse, car les règles effectuent deux actions : définir des en-têtes HTTP dans le message de réponse et "minimiser" le message de réponse qu'Apigee Edge renvoie à l'application qui envoie la requête.

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

Sélectionnez Proxy Endpoints > default > PostFlow (Points de terminaison du proxy > Par défaut > PostFlow) dans le volet Navigator (Navigateur).

La configuration XML correspondante pour le 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> se compose de plusieurs éléments <Step>. Chaque étape appelle l'une des règles que vous créez dans le reste de cette section. Ces règles associent un code JavaScript au flux de proxy d'API, et l'emplacement de l' association de la règle détermine le moment où le code JavaScript s'exécute.
<Response> : l'élément <Response> inclut également des éléments <Steps>. Ces étapes appellent également des règles chargées de traiter la réponse finale de la cible (qui, dans cet exemple, est la cible du service factice 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

Le code JavaScript (comme les scripts Python, les fichiers JAR Java, les fichiers XSLT, etc.) est stocké 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 progressez, le code 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 en savoir plus sur le stockage des ressources au niveau de l'organisation et de l'environnement, consultez la section Fichiers de ressources.

Essayer

Pour obtenir des instructions sur le déploiement et l'appel du proxy, consultez le fichier README du livre de recettes 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 de l'interface utilisateur 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'option curl -v est utilisée dans le script shell pour afficher les en-têtes HTTP du message de réponse modifié par le code JavaScript.

Vous pouvez envoyer directement une requête comme suit :

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

Si le code JavaScript s'exécute correctement, vous verrez une réponse semblable à la suivante :

< 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 code JavaScript pour que vos modifications prennent effet.

Erreurs de script

Vous verrez inévitablement des erreurs lorsque vous écrirez du code JavaScript. Le format des erreurs JavaScript que vous verrez émises par un proxy d'API est présenté 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 d'implémenter une fonctionnalité spécifique. Utilisez des règles prêtes à l'emploi dans la mesure du possible et évitez de coder toute la logique de votre proxy d'API en JavaScript. Même si Apigee Edge exploite le code JavaScript compilé pour améliorer les performances, il est peu probable que le code JavaScript soit aussi performant que les règles. Le code JavaScript peut être plus difficile à gérer et à déboguer. Réservez le code JavaScript aux fonctionnalités propres à vos besoins.

Si les performances sont un problème pour les fonctionnalités personnalisées, utilisez Java dans la mesure du possible.

Résumé

Dans cette section du livre de recettes, vous avez appris comment inclure du code JavaScript dans une configuration de proxy d'API pour implémenter un comportement personnalisé. Le comportement personnalisé implémenté par les exemples montre comment obtenir les variables et, et comment analyser le code JSON et créer des messages de réponse personnalisés.