AWS SDK for JavaScript v2 はサポート終了となりました。[AWS SDK for JavaScript v3](https://docs.aws.amazon.com//sdk-for-javascript/v3/developer-guide/) に移行することをお勧めします。その他の詳細、移行方法については、こちらの[発表内容](https://aws.amazon.com/blogs//developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/)を参照してください。
# リクエストオブジェクトのイベントリスナーの使用
サービスオブジェクトメソッドを呼び出すときに、無名コールバック関数を作成してパラメータとして渡さない場合、メソッド呼び出しは `AWS.Request` オブジェクトを生成します。このオブジェクトは `send` メソッドを使用して手動で送信する必要があります。
レスポンスを処理するには、`AWS.Request` オブジェクトのイベントリスナーを作成して、メソッド呼び出しのコールバック関数を登録する必要があります。次の例は、サービスオブジェクトメソッドを呼び出すための `AWS.Request` オブジェクトと、正常に返された場合のイベントリスナーを作成する方法を示しています。
```
// 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();
```
`send` オブジェクトの `AWS.Request` メソッドが呼び出された後、サービスオブジェクトが `AWS.Response` オブジェクトを受け取った時にイベントハンドラが実行されます。
`AWS.Request` オブジェクトの詳細については、 API リファレンスの「[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) 」を参照してください。`AWS.Response` オブジェクトの詳細については、 API リファレンスの「[レスポンスオブジェクトの使用](the-response-object.md) 」または「[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html)」を参照してください。
## 複数のコールバックの連結
任意のリクエストオブジェクトで複数のコールバックを登録できます。複数のコールバックを異なるイベントに登録するか、または同じイベントに対して登録できます。また、次の例のようにコールバックを連結させることもできます。
```
request.
on('success', function(response) {
console.log("Success!");
}).
on('error', function(response) {
console.log("Error!");
}).
on('complete', function() {
console.log("Always!");
}).
send();
```
## リクエストオブジェクトの完了イベント
`AWS.Request` オブジェクトは、各サービスオペレーションメソッドのレスポンスに基づいてこれらの完了イベントを発生させます。
+ `success`
+ `error`
+ `complete`
これらのイベントのいずれかに対応するコールバック関数を登録できます。すべてのリクエストオブジェクトイベントの完全なリストについては、API リファレンスの「[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html)」を参照してください。
### 成功イベント
`success` イベントは、サービスオブジェクトから受け取った正常なレスポンスに応じて発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('success', function(response) {
// event handler code
});
```
レスポンスは、サービスからのシリアル化されたレスポンスデータを含む `data` プロパティを提供します。例えば、Amazon S3 サービスオブジェクトの `listBuckets` メソッドに対する以下の呼び出し
```
s3.listBuckets.on('success', function(response) {
console.log(response.data);
}).send();
```
レスポンスを返してから、以下の `data` プロパティの内容をコンソールに出力します。
```
{ Owner: { ID: '...', DisplayName: '...' },
Buckets:
[ { Name: 'someBucketName', CreationDate: someCreationDate },
{ Name: 'otherBucketName', CreationDate: otherCreationDate } ],
RequestId: '...' }
```
### エラーイベント
`error` イベントは、サービスオブジェクトから受け取ったエラーレスポンスに応じて発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('error', function(error, response) {
// event handling code
});
```
`error` イベントが発生すると、レスポンスの `data` プロパティの値は `null` になり、`error` プロパティにはエラーデータが含まれます。関連付けられた `error` オブジェクトは、登録済みコールバック関数への最初のパラメータとして渡されます。たとえば、以下のコードは、
```
s3.config.credentials.accessKeyId = 'invalid';
s3.listBuckets().on('error', function(error, response) {
console.log(error);
}).send();
```
エラーを返してから、以下のエラーデータをコンソールに出力します。
```
{ code: 'Forbidden', message: null }
```
### 完了イベント
呼び出しが成功したか、エラーになったかにかかわらず、`complete` イベントはサービスオブジェクト呼び出しが終了したときに発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('complete', function(response) {
// event handler code
});
```
成功またはエラーに関係なく実行する必要があるすべてのリクエストのクリーンアップを処理するには、`complete` イベントコールバックを使用します。`complete` イベントのコールバック内でレスポンスデータを使用する場合は、次の例に示すように、どちらかにアクセスする前にまず `response.data` か `response.error` のプロパティを確認してください。
```
request.on('complete', function(response) {
if (response.error) {
// an error occurred, handle it
} else {
// we can use response.data here
}
}).send();
```
## リクエストオブジェクトの HTTP イベント
`AWS.Request` オブジェクトは、各サービスオペレーションメソッドのレスポンスに基づいてこれらの HTTP イベントを発生させます。
+ `httpHeaders`
+ `httpData`
+ `httpUploadProgress`
+ `httpDownloadProgress`
+ `httpError`
+ `httpDone`
これらのイベントのいずれかに対応するコールバック関数を登録できます。すべてのリクエストオブジェクトイベントの完全なリストについては、API リファレンスの「[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html)」を参照してください。
### httpHeaders イベント
`httpHeaders` イベントは、ヘッダーがリモートサーバーによって送信されたときに発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('httpHeaders', function(statusCode, headers, response) {
// event handling code
});
```
コールバック関数の `statusCode` パラメータは HTTP ステータスコードです。`headers` パラメータにはレスポンスヘッダーが入ります。
### httpData イベント
`httpData` イベントは、サービスからのレスポンスデータパケットをストリーミングするために発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('httpData', function(chunk, response) {
// event handling code
});
```
通常、このイベントは、レスポンス全体をメモリにロードするのが現実的ではない場合に、大量のレスポンスをチャンクに分けて受信するために使用されます。このイベントには、サーバーからの実際のデータの一部を含む、追加の `chunk` パラメータがあります。
`httpData` イベントのコールバックを登録すると、レスポンスの `data` プロパティにはリクエスト用にシリアル化された出力全体が含まれます。組み込みハンドラ用の余分な解析とメモリーのオーバーヘッドがない場合、デフォルトの `httpData` リスナーを削除する必要があります。
### httpDownloadProgress と httpUploadProgress イベント
`httpUploadProgress` イベントは、HTTP リクエストがさらにデータをアップロードしたときに発生します。同様に、`httpDownloadProgress` イベントは、HTTP リクエストがさらにデータをダウンロードしたときに発生します。次に、これらのイベントのコールバック関数を登録する方法を示します。
```
request.on('httpUploadProgress', function(progress, response) {
// event handling code
})
.on('httpDownloadProgress', function(progress, response) {
// event handling code
});
```
コールバック関数の `progress` パラメータには、リクエストのロード済みバイト数と合計バイト数を含むオブジェクトが含まれています。
### httpError イベント
`httpError` イベントは、HTTP リクエストが失敗した場合に発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('httpError', function(error, response) {
// event handling code
});
```
コールバック関数の `error` パラメータには、スローされたエラーが含まれています。
### httpDone イベント
`httpDone` イベントは、サーバーのデータ送信が終了すると発生します。次に、このイベントのコールバック関数を登録する方法を示します。
```
request.on('httpDone', function(response) {
// event handling code
});
```