[適用於 JavaScript 的 AWS SDK V3 API 參考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)詳細說明 第 3 版 適用於 JavaScript 的 AWS SDK (V3) 的所有 API 操作。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 非同步呼叫服務
<a name="calling-services-asynchronously"></a>

透過軟體開發套件提出的所有請求皆為非同步執行。編寫瀏覽器指令碼時，請務必注意這點。Web 瀏覽器中執行的 JavaScript 通常只有一個執行緒。對 AWS 服務進行非同步呼叫後，瀏覽器指令碼會繼續執行，而且在過程中可以嘗試在傳回之前執行取決於該非同步結果的程式碼。

對 AWS 服務進行非同步呼叫包括管理這些呼叫，讓您的程式碼在資料可用之前不會嘗試使用資料。本節中的主題會說明管理非同步呼叫的重要性，並詳細解說可用來管理這些呼叫的不同技術。

雖然您可以使用任何這些技術來管理非同步呼叫，但我們建議您對所有新程式碼使用非同步/等待。

非同步/等待  
我們建議您使用此技術，因為它是 V3 中的預設行為。

promise  
在不支援非同步/等待的瀏覽器中使用此技術。

回呼  
避免使用回呼，但非常簡單的情況除外。不過，您可能會發現它對遷移案例很有用。

**Topics**
+ [管理非同步呼叫](making-asynchronous-calls.md)
+ [使用非同步/等待](using-async-await.md)
+ [使用 JavaScript 承諾](using-promises.md)
+ [使用匿名回呼函數](using-a-callback-function.md)

# 管理非同步呼叫
<a name="making-asynchronous-calls"></a>

舉例來說，回流的客戶能經由電子商務網站的首頁進行登入。對登入的客戶而言，這項功能的部分優點是網站會在客戶登入後，根據其特定偏好設定來自訂本身版面。為實現此目標，必須滿足以下條件：

1. 客戶必須使用其登入憑證登入並進行驗證。

1. 系統可從客戶資料庫請求客戶的偏好設定。

1. 資料庫需提供客戶的偏好設定，以便系統在載入網頁前使用該設定自訂網站。

如果您是同步執行這些任務，則每個任務必須在下一個任務開始之前完成。在客戶偏好設定從資料庫傳回之前，網頁將無法完成載入。但是，當系統將資料庫查詢傳送至伺服器後，網路瓶頸、異常高的資料庫流量，或是行動裝置連線品質不佳，都可能造成客戶資料接收延遲，甚至失敗。

若要防止網站在這些條件下凍結，請以非同步方式呼叫資料庫。開始執行資料庫呼叫後，您能夠傳送非同步請求，讓程式碼能繼續正常運作。如果您沒有適當管理非同步呼叫的回應，程式碼就有可能在資料尚不可用的情況下，嘗試使用資料庫原先應回傳的相關資訊。

![\[說明同步和非同步執行間的差異。\]](http://docs.aws.amazon.com/zh_tw/sdk-for-javascript/v3/developer-guide/images/async-vs-sync.png)


# 使用非同步/等待
<a name="using-async-await"></a>

你應考慮使用 async/await，而非 Promise。Async 函數比使用 Promise 更簡單，採用的樣板更少。Await 僅可在 async 函數中使用，以非同步方式等待值。

下列範例使用 async/await 列出 中的所有 Amazon DynamoDB 資料表` us-west-2`。

**注意**  
要執行此範例：  
在專案的命令列`npm install @aws-sdk/client-dynamodb`中輸入 來安裝 適用於 JavaScript 的 AWS SDK DynamoDB 用戶端。
請確定您已正確設定 AWS 登入資料。如需詳細資訊，請參閱[設定登入資料](setting-credentials.md)。

```
import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";
(async function () {
  const dbClient = new DynamoDBClient({ region: "us-west-2" });
  const command = new ListTablesCommand({});

  try {
    const results = await dbClient.send(command);
    console.log(results.TableNames.join('\n'));
  } catch (err) {
    console.error(err)
  }
})();
```

**注意**  
 並非所有瀏覽器都支援非同步/等待。如需具有[非同步/等待支援的瀏覽器清單](https://caniuse.com/#feat=async-functions)，請參閱非同步函數。

# 使用 JavaScript 承諾
<a name="using-promises"></a>

使用服務用戶端的 適用於 JavaScript 的 AWS SDK v3 方法 `ListTablesCommand` () 進行服務呼叫和管理非同步流程，而不是使用回呼。下列範例顯示如何在 中取得 Amazon DynamoDB 資料表的名稱`us-west-2`。

```
import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbClient = new DynamoDBClient({ region: 'us-west-2' });

dbClient.listtables(new ListTablesCommand({}))
  .then(response => {
    console.log(response.TableNames.join('\n'));
  })
  .catch((error) => {
    console.error(error);
  });
```

## 協調多個承諾
<a name="multiple-promises"></a>

在某些情況下，程式碼必須發出多個非同步呼叫，且唯有在這些呼叫全部成功回傳時，才需要採取動作。如果您要透過 promise 來管理個別非同步方法呼叫，則可建立採用 `all` 方法的額外 promise。

您傳遞至方法的 promise 陣列都達成時，此方法即達成這個全域 promise。promise 傳遞至 `all` 方法的陣列值，會傳遞至回呼函數。

在下列範例中， AWS Lambda 函數必須對 Amazon DynamoDB 進行三次非同步呼叫，但只能在完成每次呼叫的承諾之後才能完成。

```
const values = await Promise.all([firstPromise, secondPromise, thirdPromise]);

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 values;
```

## 瀏覽器和 Node.js 對 promises 的支援
<a name="browser-node-promise-support"></a>

對原生 JavaScript promise (ECMAScript 2015) 的支援將視程式碼執行的 JavaScript 引擎與版本而定。為了協助判斷程式碼需要執行的每個環境中對 JavaScript 承諾的支援，請參閱 GitHub 上的 [ECMAScript 相容性資料表](https://compat-table.github.io/compat-table/es6/)。

# 使用匿名回呼函數
<a name="using-a-callback-function"></a>

每個服務物件方法都可以接受匿名回呼函數作為最後一個參數。此回呼函數的簽章如下所示。

```
function(error, data) {
    // callback handling code
};
```

當系統傳回成功回應或錯誤資料時，這類回呼函數即會開始執行。如果方法呼叫成功，回應內容便可供 `data` 參數中的回呼函數使用；如果呼叫不成功，則 `error` 參數會提供失敗的詳細資訊。

回呼函數內部的程式碼通常會測試錯誤，並處理傳回的錯誤。若沒有傳回錯誤，該程式碼就會擷取來自 `data` 參數的回應資料。回呼函數的基本形式如下方範例所示。

```
function(error, data) {
    if (error) {
        // error handling code
        console.log(error);
    } else {
        // data handling code
        console.log(data);
    }
};
```

在上述範例中，錯誤或所傳回資料的詳細資訊都會記錄到主控台。在接下來的範例中，系統會將傳遞的回呼函數做為呼叫服務物件方法的一部分。

```
ec2.describeInstances(function(error, data) {
  if (error) {
    console.log(error); // an error occurred
  } else {
    console.log(data); // request succeeded
  }
});
```