[適用於 JavaScript 的 AWS SDK V3 API 參考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)詳細說明 第 3 版 適用於 JavaScript 的 AWS SDK (V3) 的所有 API 操作。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 從 2.x 版遷移至 3.x 版 適用於 JavaScript 的 AWS SDK
適用於 JavaScript 的 AWS SDK 第 3 版是第 2 版的主要重寫。本節說明兩個版本之間的差異，並說明如何從適用於 JavaScript 的 SDK 第 2 版遷移到第 3 版。
## 使用 codemod 將程式碼遷移至適用於 JavaScript 的 SDK v3
適用於 JavaScript 的 AWS SDK 第 3 版 (v3) 隨附用戶端組態和公用程式的現代化界面，其中包括登入資料、Amazon S3 分段上傳、DynamoDB 文件用戶端、等待程式等。您可以在 [適用於 JavaScript 的 AWS SDK GitHub 儲存庫的遷移指南](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md)中找到 v2 中的變更，以及每項變更的 v3 對等變更。
若要充分利用 適用於 JavaScript 的 AWS SDK v3，我們建議您使用如下所述的 Codemod 指令碼。
### 使用 Codemod 遷移現有的 v2 程式碼
[aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod) 中的 Codemod 指令碼集合有助於遷移現有的 適用於 JavaScript 的 AWS SDK (v2) 應用程式，以使用 v3 APIs。您可以執行轉換，如下所示。
```
$ npx aws-sdk-js-codemod -t v2-to-v3 PATH...
```
例如，假設您有下列程式碼，這會從 v2 和呼叫`listTables`操作建立 Amazon DynamoDB 用戶端。
```
// example.ts
import AWS from "aws-sdk";
const region = "us-west-2";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise()
.then(console.log)
.catch(console.error);
```
您可以在 上執行我們的`v2-to-v3`轉換`example.ts`，如下所示。
```
$ npx aws-sdk-js-codemod -t v2-to-v3 example.ts
```
轉換會將 DynamoDB 匯入轉換為 v3，建立 v3 用戶端並呼叫 `listTables`操作，如下所示。
```
// example.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";
const region = "us-west-2";
const client = new DynamoDB({ region });
await client.listTables({})
.then(console.log)
.catch(console.error);
```
我們已針對常見的使用案例實作轉換。如果您的程式碼未正確轉換，請使用範例輸入碼和觀察/預期的輸出碼建立[錯誤報告](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=bug%2Ctriage&template=bug_report.yml&title=%5BBug%3F%5D%3A+)或[功能請求](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=enhancement&template=feature_request.yml&title=%5BFeature%5D%3A+)。如果您的特定使用案例已在[現有問題](https://github.com/awslabs/aws-sdk-js-codemod/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) 中回報，請透過 upvote 顯示您的支援。
## 第 3 版中的新功能
適用於 JavaScript (v3) 的 SDK 第 3 版包含下列新功能。
模組化套件
使用者現在可以為每個服務使用個別的套件。
新的中介軟體堆疊
使用者現在可以使用中介軟體堆疊來控制操作呼叫的生命週期。
此外，軟體開發套件是以 TypeScript 撰寫，它有許多優點，例如靜態輸入。
**重要**
本指南中的 v3 程式碼範例是以 ECMAScript 6 (ES6) 撰寫。ES6 帶來新的語法和新功能，讓您的程式碼更現代化、更易讀，並執行更多操作。ES6 要求您使用 Node.js 13.x 版或更新版本。若要下載並安裝最新版本的 Node.js，請參閱 [Node.js 下載](https://nodejs.org/en/download/)。如需詳細資訊，請參閱[JavaScript ES6/CommonJS 語法](sdk-example-javascript-syntax.md)。
## 模組化套件
適用於 JavaScript (v2) 的 SDK 第 2 版要求您使用整個 AWS SDK，如下所示。
```
var AWS = require("aws-sdk");
```
如果您的應用程式使用許多 AWS 服務，則載入整個 SDK 不是問題。不過，如果您只需要使用一些 AWS 服務，這表示使用您不需要或使用的程式碼來增加應用程式的大小。
在 v3 中，您只能載入和使用您需要的個別 AWS 服務。這會顯示在下列範例中，可讓您存取 Amazon DynamoDB (DynamoDB)。
```
import { DynamoDB } from "@aws-sdk/client-dynamodb";
```
您不僅可以載入和使用個別 AWS 服務，還可以載入和僅使用您需要的服務命令。這會顯示在下列範例中，可讓您存取 DynamoDB 用戶端和 `ListTablesCommand`命令。
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
```
**重要**
您不應該將子模組匯入模組。例如，下列程式碼可能會導致錯誤。
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";
```
以下是正確的程式碼。
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";
```
### 比較程式碼大小
在版本 2 (v2) 中 `us-west-2` ，列出區域中所有 Amazon DynamoDB 資料表的簡單程式碼範例可能如下所示。
```
var AWS = require("aws-sdk");
// Set the Region
AWS.config.update({ region: "us-west-2" });
// Create DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
// Call DynamoDB to retrieve the list of tables
ddb.listTables({ Limit: 10 }, function (err, data) {
if (err) {
console.log("Error", err.code);
} else {
console.log("Tables names are ", data.TableNames);
}
});
```
v3 如下所示。
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({ region: "us-west-2" });
try {
const results = await dbclient.send(new ListTablesCommand);
for (const item of results.TableNames) {
console.log(item);
}
} catch (err) {
console.error(err)
}
```
`aws-sdk` 套件會將約 40 MB 新增至您的應用程式。將 取代 `var AWS = require("aws-sdk")`為 會將額外負荷`import {DynamoDB} from "@aws-sdk/client-dynamodb"`降低到 3 MB 左右。將匯入限制為僅 DynamoDB 用戶端和`ListTablesCommand`命令會將額外負荷減少到小於 100 KB。
```
// Load the DynamoDB client and ListTablesCommand command for Node.js
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});
```
### 在 v3 中呼叫命令
您可以使用 v2 或 v3 命令在 v3 中執行操作。若要使用 v3 命令，您可以匯入命令和必要的 AWS Services 套件用戶端，並使用非同步/等待模式`.send`的方法執行命令。
若要使用 v2 命令，請匯入所需的 AWS 服務套件，並使用回呼或非同步/等待模式直接在套件中執行 v2 命令。
#### 使用 v3 命令
v3 為每個 AWS 服務套件提供一組命令，讓您能夠對該 AWS 服務執行操作。安裝 AWS 服務之後，您可以在專案的 中瀏覽可用的命令 `node-modules/@aws-sdk/client-{{PACKAGE_NAME}}/commands folder.`
您必須匯入要使用的命令。例如，下列程式碼會載入 DynamoDB 服務和 `CreateTableCommand`命令。
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
```
若要以建議的非同步/等待模式呼叫這些命令，請使用下列語法。
```
{{CLIENT}}.send(new {{XXX}}Command);
```
例如，下列範例會使用建議的非同步/等待模式建立 DynamoDB 資料表。
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
TableName: {{TABLE_NAME}}
};
try {
const data = await dynamodb.send(new CreateTableCommand(tableParams));
console.log("Success", data);
} catch (err) {
console.log("Error", err);
};
```
#### 使用 v2 命令
若要在適用於 JavaScript 的 SDK 中使用 v2 命令，您可以匯入完整的 AWS 服務套件，如下列程式碼所示。
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
```
若要以建議的非同步/等待模式呼叫 v2 命令，請使用下列語法。
```
{{client}}.{{command}}({{parameters}});
```
下列範例使用 v2 `createTable`命令，使用建議的非同步/等待模式建立 DynamoDB 資料表。
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
const dynamoDB = new DynamoDB({ region: 'us-west-2' });
var tableParams = {
TableName: {{TABLE_NAME}}
};
async function run() => {
try {
const data = await dynamoDB.createTable(tableParams);
console.log("Success", data);
}
catch (err) {
console.log("Error", err);
}
};
run();
```
下列範例使用 v2 `createBucket`命令，使用回呼模式建立 Amazon S3 儲存貯體。
```
const { S3 } = require('@aws-sdk/client-s3');
const s3 = new S3({ region: 'us-west-2' });
var bucketParams = {
Bucket : {{BUCKET_NAME}}
};
function run() {
s3.createBucket(bucketParams, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Location);
}
})
};
run();
```
## 新的中介軟體堆疊
開發套件的 v2 可讓您透過將事件接聽程式連接至請求，在生命週期的多個階段修改請求。這種方法可能會讓偵錯請求生命週期內發生錯誤的情況變得困難。
在 v3 中，您可以使用新的中介軟體堆疊來控制操作呼叫的生命週期。此方法提供幾個好處。對請求物件進行任何變更後，堆疊中的每個中介軟體階段都會呼叫下一個中介軟體階段。這也讓堆疊中的偵錯問題更容易，因為您可以確切看到呼叫了哪些中介軟體階段，導致錯誤。
下列範例會使用中介軟體，將自訂標頭新增至 Amazon DynamoDB 用戶端 （我們先前建立並顯示）。第一個引數是接受 的函數 `next`，這是堆疊中要呼叫的下一個中介軟體階段，而 `context`則是包含所呼叫操作相關資訊的物件。函數會傳回接受 的函數`args`，這是包含傳遞給 操作和 請求的參數的物件。它會傳回使用 呼叫下一個中介軟體的結果`args`。
```
dbclient.middlewareStack.add(
(next, context) => args => {
args.request.headers["Custom-Header"] = "value";
return next(args);
},
{
name: "my-middleware",
override: true,
step: "build"
}
);
dbclient.send(new PutObjectCommand(params));
```