La AWS SDK pour JavaScript v2 est arrivée end-of-support. Nous vous recommandons de migrer vers la [AWS SDK pour JavaScript version 3](https://docs.aws.amazon.com//sdk-for-javascript/v3/developer-guide/). Pour plus de détails et d'informations sur la façon de migrer, veuillez consulter cette [annonce](https://aws.amazon.com/blogs//developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/). Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Appel de services de façon asynchrone Toutes les demandes effectuées via le kit SDK sont asynchrones. Il est important de garder cela à l'esprit lorsque vous rédigez des scripts de navigateur. JavaScript l'exécution dans un navigateur Web ne comporte généralement qu'un seul thread d'exécution. Après avoir effectué un appel asynchrone à un AWS service, le script du navigateur continue de s'exécuter et peut ainsi essayer d'exécuter du code qui dépend de ce résultat asynchrone avant qu'il ne soit renvoyé. Les appels asynchrones à un AWS service incluent la gestion de ces appels afin que votre code n'essaie pas d'utiliser des données avant qu'elles ne soient disponibles. Les rubriques de cette section expliquent pourquoi il est nécessaire de gérer les appels asynchrones et détaillent les différentes techniques de gestion disponibles. **Topics** + [Gestion des appels asynchrones](making-asynchronous-calls.md) + [Utilisation d'une fonction de rappel anonyme](using-a-callback-function.md) + [Utilisation d'un écouteur d'événements d'un objet de demande](using-a-response-event-handler.md) + [Utilisation d’async/await](using-async-await.md) + [Utiliser les JavaScript promesses](using-promises.md) # Gestion des appels asynchrones Par exemple, la page d'accueil d'un site e-commerce autorise le renvoi de la connexion des utilisateurs. Pour les clients qui se connectent, cela présente notamment l'avantage, après connexion, de disposer d'une personnalisation en fonction de leurs préférences. Pour cela : 1. Le client doit se connecter et être validé avec ses identifiants de connexion. 1. La demande des préférences du client est faite auprès d'une base de données client. 1. La base de données fournit les préférences du client qui sont utilisées pour personnaliser le site avant le chargement de la page. Si ces tâches s'exécutent de façon synchrone, chaque tâche doit se terminer avant le démarrage de la suivante. Le chargement de la page web ne pourrait donc pas se terminer avant que la base de données ait renvoyé les préférences du client. Cependant, une fois que la requête de base de données est envoyée au serveur, la réception des données client peut être retardée ou même échouer en raison d'un goulot d'étranglement, d'un trafic de base de données exceptionnellement dense ou d'une mauvaise connexion d'un appareil mobile. Pour empêcher le blocage du site web dans ces conditions, appelez la base de données de façon asynchrone. Après l'exécution de l'appel de base de données, si vous envoyez une demande asynchrone, votre code continue de s'exécuter comme prévu. Si vous ne gérez pas correctement la réponse d'un appel asynchrone, votre code peut tenter d'utiliser les informations attendues de la base de données alors que ces données ne sont pas encore disponibles. ![\[Différence entre une exécution synchrone et une exécution asynchrone.\]](http://docs.aws.amazon.com/fr_fr/sdk-for-javascript/v2/developer-guide/images/async-vs-sync.png) # Utilisation d'une fonction de rappel anonyme Chaque méthode d'objet de service qui crée un objet `AWS.Request` peut accepter une fonction de rappel anonyme en tant que dernier paramètre. La signature de cette fonction de rappel est : ``` function(error, data) { // callback handling code } ``` Cette fonction de rappel est exécutée lorsqu'une réponse positive ou des données d'erreur sont renvoyées. Si l'appel de méthode aboutit, le contenu de la réponse est disponible pour la fonction de rappel dans le paramètre `data`. Si l'appel n'aboutit pas, les détails relatifs à l'échec sont disponibles dans le paramètre `error`. En général, le code à l'intérieur de la fonction de rappel effectue un test afin d'identifier une éventuelle erreur. Si une erreur est renvoyée, elle est traitée par le code. Si aucune erreur n'est renvoyée, le code récupère les données dans la réponse du paramètre `data`. La forme de base de la fonction de rappel ressemble à cet exemple. ``` function(error, data) { if (error) { // error handling code console.log(error); } else { // data handling code console.log(data); } } ``` Dans l'exemple précédent, les détails de l'erreur ou ceux des données renvoyées sont consignés dans la console. Voici un exemple illustrant une fonction de rappel transmise dans le cadre de l'appel d'une méthode sur un objet de service. ``` new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(function(error, data) { if (error) { console.log(error); // an error occurred } else { console.log(data); // request succeeded } }); ``` ## Accès aux objets de demande et de réponse Dans la fonction de rappel, le JavaScript mot-clé `this` fait référence à l'`AWS.Response`objet sous-jacent pour la plupart des services. Dans l'exemple suivant, la propriété `httpResponse` d'un objet `AWS.Response` est utilisée dans une fonction de rappel afin de consigner les données de réponse brutes et les en-têtes dans le but de faciliter le débogage. ``` new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(function(error, data) { if (error) { console.log(error); // an error occurred // Using this keyword to access AWS.Response object and properties console.log("Response data and headers: " + JSON.stringify(this.httpResponse)); } else { console.log(data); // request succeeded } }); ``` En outre, étant donné que l'objet `AWS.Response` possède une propriété `Request` qui contient l'objet `AWS.Request` qui a été envoyé par l'appel de méthode d'origine, vous pouvez également accéder aux détails de la demande. # Utilisation d'un écouteur d'événements d'un objet de demande Si vous ne créez pas de fonction de rappel anonyme et que vous n'en transmettez pas en tant que paramètre lorsque vous appelez une méthode d'objet de service, l'appel de méthode génère un objet `AWS.Request` qui doit être envoyé manuellement à l'aide de sa méthode `send`. Pour traiter la réponse, vous devez créer un écouteur d'événements pour l'objet `AWS.Request` afin d'enregistrer une fonction de rappel pour l'appel de méthode. L'exemple suivant montre comment créer l'objet `AWS.Request` pour appeler une méthode d'objet de service et l'écouteur d'événements afin que le renvoi aboutisse. ``` // create the AWS.Request object var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(); // register a callback event handler request.on('success', function(response) { // log the successful data response console.log(response.data); }); // send the request request.send(); ``` Lorsque la méthode `send` sur l'objet `AWS.Request` est appelée, le gestionnaire d'événements s'exécute lorsque l'objet de service reçoit un objet `AWS.Response`. Pour plus d'informations sur l'`AWS.Request`objet, consultez [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html)la référence de l'API. Pour plus d'informations sur l'`AWS.Response`objet, consultez [Utilisation de l'objet de réponse](the-response-object.md) ou consultez [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html)la référence de l'API. ## Création de chaînes de plusieurs rappels Vous pouvez enregistrer plusieurs rappels sur un objet de demande. Plusieurs rappels peuvent être enregistrés pour différents événements ou pour un même événement. Vous pouvez également créer des chaînes de rappels comme l'illustré dans l'exemple suivant. ``` request. on('success', function(response) { console.log("Success!"); }). on('error', function(response) { console.log("Error!"); }). on('complete', function() { console.log("Always!"); }). send(); ``` ## Événements d'achèvement d'objet de demande L'objet `AWS.Request` génère ces événements d'achèvement en fonction de la réponse de chaque méthode d'opération de service : + `success` + `error` + `complete` Vous pouvez enregistrer une fonction de rappel en réponse à ces événements. Pour obtenir la liste complète de tous les événements liés aux objets de requête, consultez [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html)la référence de l'API. ### L'événement success L'événement `success` est généré en cas de réponse positive reçue de l'objet de service. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('success', function(response) { // event handler code }); ``` La réponse fournit une propriété `data` qui contient les données de la réponse sérialisée provenant du service. Par exemple, l'appel suivant à la `listBuckets` méthode de l'objet de service Amazon S3 ``` s3.listBuckets.on('success', function(response) { console.log(response.data); }).send(); ``` renvoie la réponse, puis affiche le contenu de la propriété `data` suivant dans la console. ``` { Owner: { ID: '...', DisplayName: '...' }, Buckets: [ { Name: 'someBucketName', CreationDate: someCreationDate }, { Name: 'otherBucketName', CreationDate: otherCreationDate } ], RequestId: '...' } ``` ### L'événement error L'événement `error` est généré en cas de réponse d'erreur reçue de l'objet de service. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('error', function(error, response) { // event handling code }); ``` Lorsque l'événement `error` est déclenché, la valeur de la propriété `data` de la réponse est `null` et la propriété `error` contient les données relatives à l'erreur. L'objet `error` associé est transmis en tant que premier paramètre à la fonction de rappel enregistrée. Par exemple, le code suivant : ``` s3.config.credentials.accessKeyId = 'invalid'; s3.listBuckets().on('error', function(error, response) { console.log(error); }).send(); ``` renvoie l'erreur, puis affiche les données suivantes relatives à l'erreur dans la console. ``` { code: 'Forbidden', message: null } ``` ### L'événement complete L'événement `complete` est déclenché lorsqu'un appel d'objet de service est terminé, que l'appel ait aboutit ou non. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('complete', function(response) { // event handler code }); ``` Utilisez le rappel de l'événement `complete` pour gérer les demandes de nettoyage qui doivent s'exécuter quel que soit le résultat. Si vous utilisez des données de réponse dans un rappel pour l'événement `complete`, commencez par vérifier les propriétés `response.data` ou `response.error` avant d'essayer d'y accéder, comme illustré dans l'exemple suivant. ``` request.on('complete', function(response) { if (response.error) { // an error occurred, handle it } else { // we can use response.data here } }).send(); ``` ## Événements HTTP d'objet de demande L'objet `AWS.Request` génère ces événements HTTP en fonction de la réponse de chaque méthode d'opération de service : + `httpHeaders` + `httpData` + `httpUploadProgress` + `httpDownloadProgress` + `httpError` + `httpDone` Vous pouvez enregistrer une fonction de rappel en réponse à ces événements. Pour obtenir la liste complète de tous les événements liés aux objets de requête, consultez [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html)la référence de l'API. ### L'événement httpHeaders L'événement `httpHeaders` est déclenché lorsque des en-têtes sont envoyés par le serveur distant. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('httpHeaders', function(statusCode, headers, response) { // event handling code }); ``` Le paramètre `statusCode` pour la fonction de rappel est le code d'état HTTP. Le paramètre `headers` contient les en-têtes de la réponse. ### L'événement httpData L'événement `httpData` est déclenché pour diffuser des paquets de données de réponse à partir du service. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('httpData', function(chunk, response) { // event handling code }); ``` Cet événement est généralement utilisé pour recevoir des réponses volumineuses en plusieurs parties lorsqu'il n'est pas possible de charger l'ensemble de la réponse dans la mémoire. Cet évènement comporte un paramètre `chunk` supplémentaire qui contient une partie des données réelles provenant du serveur. Si vous enregistrez un rappel pour l'événement `httpData`, la propriété `data` de la réponse contient la totalité de la sortie sérialisée pour la demande. Vous devez supprimer l'écouteur `httpData` par défaut si vous ne disposez pas de l'analyse et de la surcharge de mémoire supplémentaires pour les gestionnaires intégrés. ### Les httpUploadProgress et httpDownloadProgress événements L'événement `httpUploadProgress` est déclenché lorsque la demande HTTP a chargé de nouvelles données. De la même manière, l'événement `httpDownloadProgress` est déclenché lorsque la demande HTTP a téléchargé de nouvelles données. Voici comment enregistrer une fonction de rappel pour ces événements. ``` request.on('httpUploadProgress', function(progress, response) { // event handling code }) .on('httpDownloadProgress', function(progress, response) { // event handling code }); ``` Le paramètre `progress` pour la fonction de rappel contient un objet comprenant le nombre d'octets chargés et le nombre total d'octets de la demande. ### L'événement httpError L'événement `httpError` est déclenché lorsque la demande HTTP échoue. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('httpError', function(error, response) { // event handling code }); ``` Le paramètre `error` pour la fonction de rappel contient l'erreur qui a été déclenchée. ### L'événement httpDone L'événement `httpDone` est déclenché lorsque le serveur termine l'envoi de données. Voici comment enregistrer une fonction de rappel pour cet événement. ``` request.on('httpDone', function(response) { // event handling code }); ``` # Utilisation d’async/await Vous pouvez utiliser le `async/await` modèle dans vos appels vers le AWS SDK pour JavaScript. La plupart des fonctions qui acceptent un rappel ne renvoient pas de promesse. Comme vous n'utilisez que des `await` fonctions qui renvoient une promesse, pour utiliser le `async/await` modèle, vous devez `.promise()` enchaîner la méthode jusqu'à la fin de votre appel et supprimer le rappel. L'exemple suivant permet async/await de répertorier toutes vos tables Amazon DynamoDB dans. `us-west-2` ``` var AWS = require("aws-sdk"); //Create an Amazon DynamoDB client service object. dbClient = new AWS.DynamoDB({ region: "us-west-2" }); // Call DynamoDB to list existing tables const run = async () => { try { const results = await dbClient.listTables({}).promise(); console.log(results.TableNames.join("\n")); } catch (err) { console.error(err); } }; run(); ``` **Note** Tous les navigateurs ne prennent pas en charge le mode async/await. Consultez la section [Fonctions asynchrones](https://caniuse.com/#feat=async-functions) pour une liste des navigateurs async/await compatibles. # Utiliser les JavaScript promesses La méthode `AWS.Request.promise` permet d'appeler une opération de service et de gérer le flux asynchrone au lieu d'utiliser des rappels. Dans Node.js et les scripts de navigateur, un objet `AWS.Request` est renvoyé lorsqu'une opération de service est appelée sans fonction de rappel. Vous pouvez appeler la méthode `send` de la demande pour effectuer l'appel de service. Toutefois, `AWS.Request.promise` lance immédiatement l'appel de service et renvoie une promesse qui est soit exécutée avec la propriété `data` de la réponse, soit rejetée avec la propriété `error` de la réponse. ``` var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(); // create the promise object var promise = request.promise(); // handle promise's fulfilled/rejected states promise.then( function(data) { /* process the data */ }, function(error) { /* handle the error */ } ); ``` L'exemple suivant renvoie une promesse qui est exécutée avec un objet `data` ou rejetée avec un objet `error`. Lorsque des promesses sont utilisées, un seul rappel n'est pas responsable de la détection des erreurs. Au lieu de cela, le rappel correct est appelé en fonction de la réussite ou de l'échec d'une demande. ``` var s3 = new AWS.S3({apiVersion: '2006-03-01', region: 'us-west-2'}); var params = { Bucket: 'bucket', Key: 'example2.txt', Body: 'Uploaded text using the promise-based method!' }; var putObjectPromise = s3.putObject(params).promise(); putObjectPromise.then(function(data) { console.log('Success'); }).catch(function(err) { console.log(err); }); ``` ## Coordination de plusieurs promesses Dans certains cas, votre code doit effectuer plusieurs appels asynchrones qui nécessitent une action uniquement lorsqu'ils sont tous renvoyés avec succès. Si vous gérez ces appels de méthode asynchrone individuels avec des promesses, vous pouvez créer une autre promesse qui utilise la méthode `all`. Cette méthode exécute cette promesse générique si et quand la série de promesses que vous transmettez dans la méthode est exécutée. La fonction de rappel reçoit une série des valeurs des promesses transmises à la méthode `all`. Dans l'exemple suivant, une AWS Lambda fonction doit effectuer trois appels asynchrones à Amazon DynamoDB, mais elle ne peut se terminer que lorsque les promesses pour chaque appel ont été remplies. ``` Promise.all([firstPromise, secondPromise, thirdPromise]).then(function(values) { console.log("Value 0 is " + values[0].toString); console.log("Value 1 is " + values[1].toString); console.log("Value 2 is " + values[2].toString); // return the result to the caller of the Lambda function callback(null, values); }); ``` ## Prise en charge du navigateur et de Node.js pour les promesses Support pour les JavaScript promesses natives (ECMAScript 2015) dépend du JavaScript moteur et de la version dans lesquels votre code s'exécute. Pour déterminer le support des JavaScript promesses dans chaque environnement dans lequel votre code doit être exécuté, consultez le [tableau de ECMAScript compatibilité](https://compat-table.github.io/compat-table/es6/) sur. GitHub ## Utilisation d'autres implémentations de promesses Outre l'implémentation native des promesses en ECMAScript 2015, vous pouvez également utiliser des bibliothèques de promesses tierces, notamment : + [bluebird](http://bluebirdjs.com) + [RSVP](https://github.com/tildeio/rsvp.js/) + [Q](https://github.com/kriskowal/q) Ces bibliothèques de promesses facultatives peuvent être utiles si vous avez besoin que votre code s'exécute dans des environnements qui ne prennent pas en charge l'implémentation native des promesses en ECMAScript 5 et ECMAScript 2015. Pour utiliser une bibliothèque de promesses tierce, définissez une dépendance de promesse sur le kit SDK en appelant la méthode `setPromisesDependency` de l'objet de configuration globale. Dans les scripts de navigateur, assurez-vous de charger la bibliothèque de promesses tierce avant de charger le kit SDK. Dans l'exemple suivant, le kit SDK est configuré pour utiliser l'implémentation dans la bibliothèque de promesses bluebird. ``` AWS.config.setPromisesDependency(require('bluebird')); ``` Pour revenir à l'utilisation de l'implémentation native de promesse du JavaScript moteur, appelez `setPromisesDependency` à nouveau en passant un nom de bibliothèque `null` au lieu d'un nom de bibliothèque.