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

Programmer des proxys d'API avec JavaScript

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Dans cette rubrique, vous allez apprendre à utiliser JavaScript pour ajouter dynamiquement des en-têtes HTTP à un message de réponse, et à 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 et définir des variables. Le deuxième exemple vous montre comment analyser JSON et construire un message à partir du résultat.

Deux exemples 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 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 JavaScript vous montre comment utiliser le contenu des messages. L'idée sous-jacente de cet exemple est qu'un service renvoie souvent plus de données que nécessaire. Le code JavaScript analyse donc 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 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"));

Le 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 du modèle d'objet JavaScript Edge. Pour en savoir plus sur le modèle d'objet, consultez la page Modèle d'objet JavaScript.

Avant de commencer

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

en quoi consistent les règles et comment les associer aux proxys ; Pour une bonne présentation des règles, consultez la section 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 stratégies 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.
Organisation d'un projet de proxy d'API sur votre système de fichiers, comme expliqué dans la documentation de référence sur la configuration des proxys d'API.
Vous devez connaître XML, JSON et JavaScript. Dans cet exemple, vous créez le proxy d'API et ses règles avec des fichiers XML qui se trouvent sur le système de fichiers.

Si vous avez téléchargé l'exemple de code, vous trouverez tous les fichiers abordés dans cet article dans le dossier d'exemple 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 stratégie appelé "Step". Une règle de type JavaScript (majuscules au niveau des notes) contient simplement une référence au nom d'un fichier JavaScript. Pour faire pointer la stratégie vers un fichier JavaScript, utilisez 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 de l'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 demande ou les messages de réponse lorsque ces messages "circulent" via le proxy d'API. Dans cet exemple, les deux JavaScripts s'exécutent dans le flux de réponse, car les stratégies ont deux fonctions: définir les 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'UI 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 de 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 stratégies que vous créez dans la suite de cet article. Ces règles associent un code JavaScript au flux de proxy de l'API, et l'emplacement du rattachement de règles détermine le moment où le code JavaScript s'exécute.
<Response> : l'élément <Response> inclut également <Steps>. Ces étapes appellent également les 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 fichiers JavaScript (comme les scripts Python, les fichiers JAR Java et les fichiers NoSQL) sont stockés en tant que ressources. Lorsque vous commencez tout juste à utiliser JavaScript, il est plus simple de stocker vos fichiers JavaScript dans le proxy d'API. À mesure que vous avancez, le code JavaScript doit être rendu 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 proxys 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

Test de 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 script JavaScript.

Vous pouvez envoyer directement une demande en procédant comme suit:

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

Si le code JavaScript s'exécute correctement, vous obtenez 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

Des erreurs se produisent inévitablement lorsque vous écrivez JavaScript. Le format des erreurs JavaScript que vous verrez émises par un proxy d'API est indiqué 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. Dans la mesure du possible, utilisez des règles prêtes à l'emploi et évitez la tentation de coder toute votre logique de 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 JavaScript soit aussi performant que les règles. JavaScript peut être plus difficile à gérer et à déboguer. Réservez JavaScript pour bénéficier d'une fonctionnalité adaptée à vos besoins.

Si les performances d'une fonctionnalité personnalisée posent problème, utilisez Java lorsque cela est possible.

Résumé

Dans cette rubrique de ce livre de recettes, vous avez appris comment inclure JavaScript dans une configuration de proxy d'API afin de mettre en œuvre un comportement personnalisé. Le comportement personnalisé mis en œuvre par les exemples montre comment obtenir des variables, et comment analyser le format JSON et créer des messages de réponse personnalisés.