[適用於 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 XXXCommand);
```
例如，下列範例會使用建議的非同步/等待模式建立 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));
```
# 適用於 JavaScript 的 AWS SDK v2 和 v3 之間的差異
本節擷取從 適用於 JavaScript 的 AWS SDK v2 到 v3 的顯著變更。由於 v3 是 v2 的模組化重寫，因此 v2 和 v3 之間的一些基本概念不同。您可以在我們的[部落格文章](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/)中了解這些變更。下列部落格文章將讓您快速上手：
+ [中的模組化套件 適用於 JavaScript 的 AWS SDK](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/)
+ [模組化 Middleware Stack 簡介 適用於 JavaScript 的 AWS SDK](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/)
從 適用於 JavaScript 的 AWS SDK v2 到 v3 的界面變更摘要如下所示。目標是協助您輕鬆找到您已熟悉的 v2 APIs的 v3 對等項目。
**Topics**
+ [用戶端建構函數](migrate-client-constructors.md)
+ [登入資料提供者](migrate-credential-providers.md)
+ [Amazon S3 考量](migrate-s3.md)
+ [DynamoDB 文件用戶端](migrate-dynamodb-doc-client.md)
+ [等待者和簽署者](migrate-waiters-signers.md)
+ [特定服務用戶端的備註](migrate-service-client-notes.md)
# 用戶端建構函數
此清單由 [v2 組態參數](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html)編製索引。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property)
+ **v2**：當服務接受承載主體時，是否要計算承載主體的 MD5 檢查總和 （目前僅在 S3 中支援）。
+ **v3**：S3 的適用命令 (PutObject、PutBucketCors 等） 會自動計算請求承載的 MD5 檢查總和。您也可以在命令的 `ChecksumAlgorithm` 參數中指定不同的檢查總和演算法，以使用不同的檢查總和演算法。您可以在 [S3 功能公告](https://aws.amazon.com/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/)中找到更多資訊。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property)
+ **v2**：剖析回應資料時是否轉換類型。
+ **v3**：**已棄用**。此選項被視為不安全類型，因為它不會從 JSON 回應轉換時間戳記或 base64 二進位檔等類型。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property)
+ **v2**：是否要套用因用戶端時鐘偏斜而失敗的時鐘偏斜修正和重試請求。
+ **v3**：**已棄用**。SDK *一律*會套用時鐘偏斜校正。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property)
+ **v2**：要套用至所有簽署時間的位移值，以毫秒為單位。
+ **v3**：無變更。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property)
+ **v2**： AWS 用來簽署請求的登入資料。
+ **v3**：無變更。它也可以是傳回登入資料的非同步函數。如果函數傳回 `expiration (Date)`，則會在過期日期時間接近時再次呼叫函數。如需[`AwsAuthInputConfig`登入資料，請參閱 v3 API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-signing/Interface/AwsAuthInputConfig/)。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property)
+ **v2**：從端點探索操作存放端點的全域快取大小。
+ **v3**：無變更。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property)
+ **v2**：是否使用服務提供的端點動態呼叫操作。
+ **v3**：無變更。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property)
+ **v2**：是否要將請求參數封送至主機名稱的字首。
+ **v3**：**已棄用**。SDK *一律*會在必要時注入主機名稱字首。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property)
要傳遞至低階 HTTP 請求的一組選項。這些選項在 v3 中的彙總方式不同。您可以提供新的 來設定它們`requestHandler`。以下是在 Node.js 執行時間中設定 http 選項的範例。您可以在 [ NodeHttpHandler 的 v3 API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/)中找到更多資訊。
根據預設，所有 v3 請求都使用 HTTPS。您只需要提供自訂 httpsAgent。
```
const { Agent } = require("https");
const { Agent: HttpAgent } = require("http");
const { NodeHttpHandler } = require("@smithy/node-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new NodeHttpHandler({
httpsAgent: new Agent({
/*params*/
}),
connectionTimeout: /*number in milliseconds*/,
socketTimeout: /*number in milliseconds*/
}),
});
```
如果您要傳遞使用 http 的自訂端點，則需要提供 httpAgent。
```
const { Agent } = require("http");
const { NodeHttpHandler } = require("@smithy/node-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new NodeHttpHandler({
httpAgent: new Agent({
/*params*/
}),
}),
endpoint: "http://example.com",
});
```
如果用戶端在瀏覽器中執行，則可使用不同的選項集。您可以在 [ FetchHttpHandler 的 v3 API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-fetch-http-handler/)中找到更多資訊。
```
const { FetchHttpHandler } = require("@smithy/fetch-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new FetchHttpHandler({
requestTimeout: /* number in milliseconds */
}),
});
```
的每個選項`httpOptions`都指定如下：
+ `proxy`
+ **v2**：透過 代理請求的 URL。
+ **v3**：您可以在為 [Node.js 設定代理之後，使用代理程式設定代理。](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-proxies.html)
+ `agent`
+ **v2**：用來執行 HTTP 請求的代理程式物件。用於連線集區。
+ **v3**：您可以設定 `httpAgent`或 `httpsAgent`，如上述範例所示。
+ `connectTimeout`
+ **v2**：在`connectTimeout`毫秒後無法與伺服器建立連線後，將通訊端設定為逾時。
+ **v3**： `connectionTimeout` 可在 [`NodeHttpHandler` 選項中使用](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/)。
+ `timeout`
+ **v2**：自動終止之前，請求可能需要的毫秒數。
+ **v3**： `socketTimeout` 可在 [`NodeHttpHandler` 選項中使用](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/)。
+ `xhrAsync`
+ **v2**：軟體開發套件是否會傳送非同步 HTTP 請求。
+ **v3**：**已棄用**。請求*一律*是非同步的。
+ `xhrWithCredentials`
+ **v2**：設定 XMLHttpRequest 物件的「withCredentials」屬性。
+ **v3**：無法使用。SDK [會繼承預設的擷取組態](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property)
+ **v2**：回應 `.write()`（如串流） 或 `.log()`（如主控台物件） 以記錄請求相關資訊的物件。
+ **v3**：無變更。v3 中提供更精細的日誌。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property)
+ **v2**：服務請求要遵循的重新導向數量上限。
+ **v3**：**已棄用**。SDK *不會*遵循重新導向，以避免意外的跨區域請求。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property)
+ **v2**：針對服務請求執行的重試次數上限。
+ **v3**：變更為 `maxAttempts`。如需詳細資訊，請參閱 [ RetryInputConfig 的 v3 API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-middleware-retry/Interface/RetryInputConfig/)。請注意， `maxAttempts`應為 `maxRetries + 1`。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property)
+ **v2**：傳送請求之前，是否應根據操作描述驗證輸入參數。
+ **v3**：**已棄用**。SDK *不會*在執行時間對用戶端進行驗證。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property)
+ **v2**：傳送服務請求的區域。
+ **v3**：無變更。它也可以是傳回區域字串的非同步函數。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property)
+ **v2**：設定可重試錯誤之重試延遲的一組選項。
+ **v3**：**已棄用**。SDK 使用`retryStrategy`用戶端建構函數選項支援更靈活的重試策略。如需詳細資訊[，請參閱 v3 API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-util-retry/)。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property)
+ **v2**：提供的端點是否處理個別儲存貯體 （如果處理根 API 端點，則為 false)。
+ **v3**：變更為 `bucketEndpoint`。如需詳細資訊，請參閱 [ bucketEndpoint 的 v3 API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-bucket-endpoint/Interface/BucketEndpointInputConfig/)。請注意，當 設定為 時`true`，您可以在請求參數中指定`Bucket`請求端點，原始端點將被覆寫。而在 v2 中，用戶端建構函數中的請求端點會覆寫`Bucket`請求參數。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property)
+ **v2**：使用簽章版本 v4 時是否停用 S3 內文簽署。
+ **v3**：重新命名為 `applyChecksum`。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property)
+ **v2**：是否強制 S3 物件的路徑樣式 URLs。
+ **v3**：重新命名為 `forcePathStyle`。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property)
+ **v2**：是否要使用從請求資源的 ARN 推斷的區域來覆寫請求區域。
+ **v3**：重新命名為 `useArnRegion`。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property)
+ **v2**：將區域設定為 'us-east-1' 時，是否要將 s3 請求傳送至全域端點或 'us-east-1' 區域端點。
+ **v3**：**已棄用**。如果區域設定為 ，S3 用戶端一律會使用區域端點`us-east-1`。您可以將區域設定為 `aws-global`，將請求傳送至 S3 全域端點。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property)
+ **v2**：是否要快取簽署請求的簽章 （覆寫 API 組態）。
+ **v3**：**已棄用**。SDK *一律*快取雜湊簽署金鑰。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property)
+ **v2**：用來簽署請求的簽章版本 （覆寫 API 組態）。
+ **v3**：**已棄用**。v2 SDK 中支援的簽章 V2 已由 取代 AWS。v3 *僅*支援簽章 v4。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property)
+ **v2**：是否為請求啟用 SSL。
+ **v3**：重新命名為 `tls`。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property)
+ **v2**：是否要將 sts 請求傳送至全域端點或區域端點。
+ **v3**：**已棄用**。如果設定為特定區域，STS 用戶端*一律*會使用區域端點。您可以將區域設定為 `aws-global`，將請求傳送至 STS 全域端點。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property)
+ **v2**：是否要搭配 S3 服務使用 Accelerate 端點。
+ **v3**：無變更。
# 登入資料提供者
在 v2 中，適用於 JavaScript 的 SDK 提供登入資料提供者清單，以及登入資料提供者鏈結，依預設可在 Node.js 上取得，嘗試從所有最常見的提供者載入 AWS 登入資料。適用於 JavaScript v3 的 SDK 可簡化登入資料提供者的界面，讓您更輕鬆地使用和撰寫自訂登入資料提供者。除了新的登入資料提供者鏈之外，適用於 JavaScript v3 的 SDK 還提供了一份登入資料提供者清單，旨在提供相當於 v2 的登入資料提供者。
以下是 v2 中的所有登入資料提供者及其 v3 中的同等項目。
## 預設登入資料提供者
如果*未*明確提供登入資料，則預設登入資料提供者是適用於 JavaScript 的 SDK 如何解析 AWS 登入資料。
+ **v2**：Node.js 中的 [CredentialProviderChain](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html) 解析來源的登入資料，順序如下：
+ [環境變數](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html)
+ [共用登入資料檔案](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html)
+ [ECS 容器憑證](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html)
+ [產生外部程序](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html)
+ [來自指定檔案的 OIDC 權杖](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html)
+ [Amazon EC2 執行個體中繼資料](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)
如果上述其中一個登入資料提供者無法解析 AWS 登入資料，則鏈結會回到下一個提供者，直到有效登入資料解析為止，而且當所有提供者都失敗時，鏈結會擲回錯誤。
在瀏覽器和 React Native 執行時間中，登入資料鏈是空的，而且登入資料必須明確設定。
+ **v3**：[defaultProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers#fromnodejsproviderchain-1)。登入資料來源和備用順序在 v3 中*不會*變更。它也支援 [AWS IAM Identity Center 登入](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)資料。
## 暫時登入資料
+ **v2**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html)代表從 擷取的臨時登入資料`AWS.STS`。如果沒有任何額外的參數，將從 `AWS.STS.getSessionToken()`操作擷取登入資料。如果提供 IAM 角色，則會改用 `AWS.STS.assumeRole()`操作來擷取角色的登入資料。 與處理 masterCredentials 和重新整理`AWS.TemporaryCredentials`的方式`AWS.ChainableTemporaryCredentials`不同。 會使用使用者傳遞的 masterCredentials `AWS.ChainableTemporaryCredentials`重新整理過期的登入資料，以支援 STS 登入資料鏈結。不過， 會在執行個體化期間`AWS.TemporaryCredentials`遞迴收合 masterCredentials，導致無法重新整理需要中繼臨時憑證的登入資料。
原始 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) 已**棄用**，以支持 `ChainableTemporaryCredentials` v2。
+ **v3**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials)。您可以從 `fromTemporaryCredentials()` `@aws-sdk/credential-providers`套件呼叫 。範例如下：
```
import { FooClient } from "@aws-sdk/client-foo";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
// const { FooClient } = require("@aws-sdk/client-foo");
// const { fromTemporaryCredentials } = require("@aws-sdk/credential-providers"); // CommonJS import
const sourceCredentials = {
// A credential can be a credential object or an async function that returns a credential object
};
const client = new FooClient({
credentials: fromTemporaryCredentials({
masterCredentials: sourceCredentials,
params: { RoleArn },
}),
});
```
## Amazon Cognito 身分登入資料
從 Amazon Cognito Identity 服務載入登入資料，通常用於瀏覽器。
+ **v2**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html)代表使用 Amazon Cognito Identity 服務從 STS Web Identity Federation 擷取的憑證。
+ **v3**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) [`@aws/credential-providers`套件](https://www.npmjs.com/package/@aws-sdk/credential-providers)提供兩個登入資料提供者函數，其中一個[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)會取得身分 ID 並呼叫 `cognitoIdentity:GetCredentialsForIdentity`，另一個[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)則會取得身分集區 ID、第一次呼叫`cognitoIdentity:GetId`時的呼叫，然後呼叫 `fromCognitoIdentity`。後續叫用後者不會重新叫用 GetId。
供應商實作 [Amazon Cognito 開發人員指南](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html)中所述的「簡化流程」。`sts:AssumeRoleWithWebIdentity` *不支援*涉及呼叫 `cognito:GetOpenIdToken` ，然後呼叫 的「傳統流程」。如果您需要，請向我們開啟[功能請求](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)。
```
// fromCognitoIdentityPool example
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentityPool } = require("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
region: "us-east-1",
credentials: fromCognitoIdentityPool({
clientConfig: cognitoIdentityClientConfig, // Optional
identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
logins: {
// Optional
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"api.twitter.com": "TWITTERTOKEN",
},
}),
});
```
```
// fromCognitoIdentity example
import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentity } = require("@aws-sdk/credential-provider-cognito-identity"); // CommonJS import
const client = new FooClient({
region: "us-east-1",
credentials: fromCognitoIdentity({
clientConfig: cognitoIdentityClientConfig, // Optional
identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
logins: {
// Optional
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"api.twitter.com": "TWITTERTOKEN",
},
}),
});
```
## Amazon EC2 中繼資料 (IMDS) 登入資料
代表從 Amazon EC2 執行個體上的中繼資料服務收到的登入資料。
+ **v2**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html)
+ **v3**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata)。建立登入資料提供者，從 Amazon EC2 執行個體中繼資料服務取得登入資料。
```
import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromInstanceMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromInstanceMetadata({
maxRetries: 3, // Optional
timeout: 0, // Optional
}),
});
```
## Amazon ECS 登入資料
代表從指定 URL 收到的登入資料。此提供者會從 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`或 `AWS_CONTAINER_CREDENTIALS_FULL_URI`環境變數指定的 URI 請求臨時登入資料。
+ **v2**： `ECSCredentials` 或 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html)
+ **v3**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata)。建立登入資料提供者，從 Amazon ECS 容器中繼資料服務取得登入資料。
```
import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
credentials: fromContainerMetadata({
maxRetries: 3, // Optional
timeout: 0, // Optional
}),
});
```
## 檔案系統登入資料
+ **v2**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html)。代表磁碟上 JSON 檔案的登入資料。
+ **v3**：**已棄用**。您可以明確讀取 JSON 檔案並提供給用戶端。如果您需要，請向我們開啟[功能請求](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)。
## SAML 登入資料提供者
+ **v2**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html)代表從 STS SAML 支援擷取的登入資料。
+ **v3**：**無法使用**。如果您需要，請向我們開啟[功能請求](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)。
## 共用登入資料檔案登入資料
從共用登入資料檔案載入登入資料 （預設為 `~/.aws/credentials` 或由`AWS_SHARED_CREDENTIALS_FILE`環境變數定義）。不同 AWS SDKs和工具都支援此檔案。如需詳細資訊，請參閱[共用組態和登入資料檔案文件](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)。
+ **v2**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html)
+ **v3**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
```
import { fromIni } from "@aws-sdk/credential-providers";
// const { fromIni } from("@aws-sdk/credential-providers");
const client = new FooClient({
credentials: fromIni({
configFilepath: "~/.aws/config", // Optional
filepath: "~/.aws/credentials", // Optional
mfaCodeProvider: async (mfaSerial) => {
// implement a pop-up asking for MFA code
return "some_code";
}, // Optional
profile: "default", // Optional
clientConfig: { region }, // Optional
}),
});
```
## Web 身分登入資料
使用 OIDC 字符從磁碟上的檔案擷取登入資料。常見於 Amazon EKS。
+ **v2**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html)
+ **v3**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile)
```
import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromTokenFile } from("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromTokenFile({
// Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
roleArn: "arn:xxxx",
// Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
roleSessionName: "session:a",
// Optional. STS client config to make the assume role request.
clientConfig: { region },
}),
});
```
## Web 聯合身分登入資料
從 STS Web 聯合身分支援擷取憑證。
+ **v2**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html)
+ **v3**： [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken)
```
import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromWebToken } from("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromWebToken({
// Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
roleArn: "arn:xxxx",
// Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
roleSessionName: "session:a",
// Optional. STS client config to make the assume role request.
clientConfig: { region },
}),
});
```
# Amazon S3 考量
## Amazon S3 分段上傳
在 v2 中，Amazon S3 用戶端包含支援使用 [Amazon S3 提供的分段上傳功能上傳](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html)大型物件[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property)的操作。
在 v3 中，[https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage)套件可供使用。它支援 v2 `upload()`操作中提供的所有功能，並同時支援 Node.js 和瀏覽器執行時間。
## Amazon S3 預先簽章的 URL
在 v2 中，Amazon S3 用戶端包含 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property)和 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property)操作，可產生使用者可用來從 Amazon S3 上傳或下載物件的 URL。
在 v3 中，[https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner)套件可供使用。此套件包含 `getSignedUrl()`和 ` getSignedUrlPromise()`操作的 函數。此[部落格文章](https://aws.amazon.com/blogs/developer/generate-presigned-url-modular-aws-sdk-javascript/)討論此套件的詳細資訊。
## Amazon S3 區域重新導向
如果將不正確的區域傳遞至 Amazon S3 用戶端，並擲回後續 ` PermanentRedirect`（狀態 301) 錯誤，則 v3 中的 Amazon S3 用戶端支援區域重新導向 （先前在 v2 中稱為 Amazon S3 全域用戶端）。您可以使用用戶端組態中的 [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/)旗標，讓 Amazon S3 用戶端遵循區域重新導向，並支援其做為全域用戶端的 函數。
**注意**
請注意，此功能可能會導致額外的延遲，因為當收到狀態為 301 的`PermanentRedirect`錯誤時，失敗的請求會以更正的區域重試。只有在您事先不知道儲存貯體的區域時 （如果），才應該使用此功能。
## Amazon S3 串流和緩衝回應
v3 SDK 偏好不緩衝潛在的大型回應。這通常發生在 Amazon S3 操作中，該`GetObject`操作在 v2 `Buffer` 中傳回 ，但在 v3 `Stream`中傳回 。
對於 Node.js，您必須使用串流或垃圾收集用戶端或其請求處理常式，透過釋放通訊端來保持對新流量的連線開啟。
```
// v2
const get = await s3.getObject({ ... }).promise(); // this buffers consumes the stream already.
```
```
// v3, consume the stream to free the socket
const get = await s3.getObject({ ... }); // object .Body has unconsumed stream
const str = await get.Body.transformToString(); // consumes the stream
// other ways to consume the stream include writing it to a file,
// passing it to another consumer like an upload, or buffering to
// a string or byte array.
```
如需詳細資訊，請參閱通訊[端耗盡](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler)一節。
# DynamoDB 文件用戶端
## 在 v3 中基本使用 DynamoDB 文件用戶端
+ 在 v2 中，您可以使用 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html)類別呼叫具有 Array、Number 和 Object 等原生 JavaScript 類型的 DynamoDB APIs。因此，它透過消除屬性值的概念，簡化了在 Amazon DynamoDB 中使用項目的操作。
+ 在 v3 中，可使用同等[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html)用戶端。它類似於 v3 SDK 的正常服務用戶端，不同之處在於其建構函數中需要基本的 DynamoDB 用戶端。
範例：
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); // CommonJS import
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocumentClient, PutCommand } = require("@aws-sdk/lib-dynamodb"); // CommonJS import
// Bare-bones DynamoDB Client
const client = new DynamoDBClient({});
// Bare-bones document client
const ddbDocClient = DynamoDBDocumentClient.from(client); // client is DynamoDB client
await ddbDocClient.send(
new PutCommand({
TableName,
Item: {
id: "1",
content: "content from DynamoDBDocumentClient",
},
})
);
```
## `Undefined` 封送時 中的值
+ 在 v2 中，物件中的`undefined`值會在向 DynamoDB 進行封送程序期間自動省略。
+ 在 v3 中， 中的預設封送行為`@aws-sdk/lib-dynamodb`已變更：不再省略具有`undefined`值的物件。若要與 v2 的功能保持一致，開發人員必須在 DynamoDB 文件用戶端`marshallOptions`的 `true`中明確將 `removeUndefinedValues` 設定為 。
範例：
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
// The DynamoDBDocumentClient is configured to handle undefined values properly
const ddbDocClient = DynamoDBDocumentClient.from(client, {
marshallOptions: {
removeUndefinedValues: true
}
});
await ddbDocClient.send(
new PutCommand({
TableName,
Item: {
id: "123",
content: undefined // This value will be automatically omitted.
array: [1, undefined], // The undefined value will be automatically omitted.
map: { key: undefined }, // The "key" will be automatically omitted.
set: new Set([1, undefined]), // The undefined value will be automatically omitted.
};
})
);
```
[套件 README](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-dynamodb/README.md) 中提供了更多範例和組態。
# 等待者和簽署者
此頁面說明 適用於 JavaScript 的 AWS SDK v3 中等待者和簽署者的使用情況。
## 等待程式
在 v2 中，所有等待程式都繫結至服務用戶端類別，您需要在等待程式的輸入中指定用戶端將等待的設計狀態。例如，您需要呼叫 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter) 來等待新建立的儲存貯體準備就緒。
在 v3 中，如果您的應用程式不需要，則不需要匯入等待程式。此外，您只能匯入需要等待特定所需狀態的等待程式。因此，您可以減少套件大小並改善效能。以下是在建立儲存貯體後等待儲存貯體就緒的範例：
```
import { S3Client, CreateBucketCommand, waitUntilBucketExists } from "@aws-sdk/client-s3"; // ES6 import
// const { S3Client, CreateBucketCommand, waitUntilBucketExists } = require("@aws-sdk/client-s3"); // CommonJS import
const Bucket = "BUCKET_NAME";
const client = new S3Client({ region: "REGION" });
const command = new CreateBucketCommand({ Bucket });
await client.send(command);
await waitUntilBucketExists({ client, maxWaitTime: 60 }, { Bucket });
```
您可以在 [適用於 JavaScript 的 AWS SDK v3 中等待程式的部落格文章中找到如何設定等待程式](https://aws.amazon.com/blogs/developer/waiters-in-modular-aws-sdk-for-javascript/)的所有內容。
## Amazon CloudFront 簽署者
在 v2 中，您可以使用 簽署存取受限 Amazon CloudFront 分佈的請求[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html)。
在 v3 中，您在 [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html)套件中提供相同的公用程式。
## Amazon RDS 簽署者
在 v2 中，您可以使用 將身分驗證字符產生到 Amazon RDS 資料庫[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html)。
在 v3 中，類似的公用程式類別可在[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html)套件中使用。
## Amazon Polly 簽署者
在 v2 中，您可以產生由 Amazon Polly 服務與 合成之語音的已簽署 URL[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html)。
在 v3 中，[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html)套件中提供了類似的公用程式函數。
# 特定服務用戶端的備註
## AWS Lambda
Lambda 調用回應類型在 v2 和 v3 中不同。
```
// v2
import { Lambda } from "@aws-sdk/client-lambda";
import AWS from "aws-sdk";
const lambda = new AWS.Lambda({ REGION });
const invoke = await lambda.invoke({
FunctionName: "echo",
Payload: JSON.stringify({ message: "hello" }),
}).promise();
// in v2, Lambda::invoke::Payload is automatically converted to string via a
// specific code customization.
const payloadIsString = typeof invoke.Payload === "string";
console.log("Invoke response payload type is string:", payloadIsString);
const payloadObject = JSON.parse(invoke.Payload);
console.log("Invoke response object", payloadObject);
```
```
// v3
const lambda = new Lambda({ REGION });
const invoke = await lambda.invoke({
FunctionName: "echo",
Payload: JSON.stringify({ message: "hello" }),
});
// in v3, Lambda::invoke::Payload is not automatically converted to a string.
// This is to reduce the number of customizations that create inconsistent behaviors.
const payloadIsByteArray = invoke.Payload instanceof Uint8Array;
console.log("Invoke response payload type is Uint8Array:", payloadIsByteArray);
// To maintain the old functionality, only one additional method call is needed:
// v3 adds a method to the Uint8Array called transformToString.
const payloadObject = JSON.parse(invoke.Payload.transformToString());
console.log("Invoke response object", payloadObject);
```
## Amazon SQS
### MD5 檢查總和
若要略過訊息內文的 MD5 檢查總和計算，請在組態物件上`md5`將 設為 *false*。否則，軟體開發套件預設會計算傳送訊息的檢查總和，以及驗證擷取訊息的檢查總和。
```
// Example: Skip MD5 checksum in Amazon SQS
import { SQS } from "@aws-sdk/client-sqs";
new SQS({
md5: false // note: only available in v3.547.0 and higher
});
```
在具有此參數的 Amazon SQS 操作`QueueUrl`中使用自訂時，在 v2 中可以提供自訂`QueueUrl`，以覆寫 Amazon SQS 用戶端的預設端點。
### 多區域訊息
您應該在 v3 中的每個區域使用一個用戶端。 AWS 區域旨在用戶端層級初始化，而不會在請求之間變更。
```
import { SQS } from "@aws-sdk/client-sqs";
const sqsClients = {
"us-east-1": new SQS({ region: "us-east-1" }),
"us-west-2": new SQS({ region: "us-west-2" }),
};
const queues = [
{ region: "us-east-1", url: "https://sqs.us-east-1.amazonaws.com/{AWS_ACCOUNT}/MyQueue" },
{ region: "us-west-2", url: "https://sqs.us-west-2.amazonaws.com/{AWS_ACCOUNT}/MyOtherQueue" },
];
for (const { region, url } of queues) {
const params = {
MessageBody: "Hello",
QueueUrl: url,
};
await sqsClients[region].sendMessage(params);
}
```
### 自訂端點
在 v3 中，使用自訂端點時，亦即與預設公有 Amazon SQS 端點不同的端點，您應該一律在 Amazon SQS 用戶端和 ` QueueUrl` 欄位上設定端點。
```
import { SQS } from "@aws-sdk/client-sqs";
const sqs = new SQS({
// client endpoint should be specified in v3 when not the default public SQS endpoint for your region.
// This is required for versions <= v3.506.0
// This is optional but recommended for versions >= v3.507.0 (a warning will be emitted)
endpoint: "https://my-custom-endpoint:8000/",
});
await sqs.sendMessage({
QueueUrl: "https://my-custom-endpoint:8000/1234567/MyQueue",
Message: "hello",
});
```
如果您不是使用自訂端點，則不需要在用戶端`endpoint`上設定 。
```
import { SQS } from "@aws-sdk/client-sqs";
const sqs = new SQS({
region: "us-west-2",
});
await sqs.sendMessage({
QueueUrl: "https://sqs.us-west-2.amazonaws.com/1234567/MyQueue",
Message: "hello",
});
```
# 補充文件
下表包含補充文件的連結，可協助您使用和了解 適用於 JavaScript 的 AWS SDK (v3)。
****
| 名稱 | 備註 |
| --- | --- |
| [SDK 用戶端](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md) | 有關初始化 SDK 用戶端和常見可設定建構函數參數的資訊。 |
| [升級備註 (2.x 到 3.x)](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md) | 有關從 適用於 JavaScript 的 AWS SDK (v2) 升級的資訊。 |
| [在 AWS Lambda Node.js 執行時間上使用 適用於 JavaScript 的 AWS SDK (v3)](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/AWS_LAMBDA.md) | AWS Lambda 使用 適用於 JavaScript 的 AWS SDK (v3) 在 內工作的最佳實務。 |
| [效能](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/performance/README.md) | 軟體 AWS 開發套件團隊如何最佳化軟體開發套件效能的資訊，並包含設定軟體開發套件以有效執行的秘訣。 |
| [TypeScript](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/TYPESCRIPT.md) | TypeScript 秘訣和與 適用於 JavaScript 的 AWS SDK (v3) 相關的FAQs。 |
| [錯誤處理](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/ERROR_HANDLING.md) | 處理與 適用於 JavaScript 的 AWS SDK (v3) 相關的錯誤的提示。 |
| [有效實務](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/EFFECTIVE_PRACTICES.md) | 使用 適用於 JavaScript 的 AWS SDK (v3) 的一般建議。 |