リクエストオブジェクトのイベントリスナーの使用 - AWS SDK for JavaScript
複数のコールバックの連結リクエストオブジェクトの完了イベントリクエストオブジェクトの HTTP イベント

AWS SDK for JavaScript v2 はサポート終了となりました。AWS SDK for JavaScript v3 に移行することをお勧めします。その他の詳細、移行方法については、こちらの発表内容を参照してください。

リクエストオブジェクトのイベントリスナーの使用

サービスオブジェクトメソッドを呼び出すときに、無名コールバック関数を作成してパラメータとして渡さない場合、メソッド呼び出しは 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();

AWS.Request オブジェクトの send メソッドが呼び出された後、サービスオブジェクトが AWS.Response オブジェクトを受け取った時にイベントハンドラが実行されます。

AWS.Request オブジェクトの詳細については、 API リファレンスの「Class: AWS.Request 」を参照してください。AWS.Response オブジェクトの詳細については、 API リファレンスの「レスポンスオブジェクトの使用 」または「Class: AWS.Response」を参照してください。

複数のコールバックの連結

任意のリクエストオブジェクトで複数のコールバックを登録できます。複数のコールバックを異なるイベントに登録するか、または同じイベントに対して登録できます。また、次の例のようにコールバックを連結させることもできます。

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 リファレンスの「Class: AWS.Request」を参照してください。

成功イベント

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 リファレンスの「Class: AWS.Request」を参照してください。

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
});