適用於 JavaScript 的 AWS SDK v2 已end-of-support。我們建議您遷移至 [適用於 JavaScript 的 AWS SDK 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();
```
呼叫 `AWS.Request` 物件上的 `send` 方法後，事件處理常式即會在服務物件收到 `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 參考[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html)中的 [使用回應物件](the-response-object.md)或 。
## 變更多個回呼
您能夠在任何請求物件上註冊多個回呼，也可為不同事件或相同事件註冊多個回呼。而且，您還能鏈結回呼，如下方範例所示。
```
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 事件
收到來自服務物件的成功回應時，系統就會引發 `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 事件
收到來自服務物件的錯誤回應時，系統就會引發 `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 事件
系統會在服務物件呼叫完成時引發 `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` 接聽程式。
### httpUploadProgress 和 httpDownloadProgress 事件
當 HTTP 請求上傳更多資料時，系統就會引發 `httpUploadProgress` 事件。同樣地，系統會在 HTTP 請求下載更多資料時引發 `httpDownloadProgress` 事件。以下是針對這些事件註冊回呼函數的方式。
```
request.on('httpUploadProgress', function(progress, response) {
// event handling code
})
.on('httpDownloadProgress', function(progress, response) {
// event handling code
});
```
回呼函數的 `progress` 參數中，包含具備載入請求和總位元組數的物件。
### httpError 事件
當 HTTP 請求失敗時，系統就會引發 `httpError` 事件。以下是針對這個事件註冊回呼函數的方式。
```
request.on('httpError', function(error, response) {
// event handling code
});
```
回呼函數的 `error` 參數內含擲回的錯誤。
### httpDone 事件
當伺服器完成資料傳送作業時，系統就會引發 `httpDone` 事件。以下是針對這個事件註冊回呼函數的方式。
```
request.on('httpDone', function(response) {
// event handling code
});
```