[适用于 JavaScript 的 AWS SDK V3 API 参考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)详细描述了 适用于 JavaScript 的 AWS SDK 版本 3 (V3) 的所有 API 操作。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 从 2.x 版迁移到 3.x 版 适用于 JavaScript 的 AWS SDK
<a name="migrating"></a>

 适用于 JavaScript 的 AWS SDK 版本 3 是对版本 2 的重大改写。本节描述了两个版本之间的区别，并说明了如何从适用的 SDK 的版本 2 迁移到版本 3 JavaScript。

## 使用 codemod 将你的代码迁移到适用于 JavaScript v3 的 SDK
<a name="migrating-to-v3"></a>

适用于 JavaScript 的 AWS SDK 版本 3 (v3) 带有用于客户端配置和实用程序的现代化界面，包括凭证、Amazon S3 分段上传、DynamoDB 文档客户端、服务员等。您可以在 repo 的[迁移指南](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md)中找到 v2 中更改的内容以及每项更改的 v3 等效内容。 适用于 JavaScript 的 AWS SDK GitHub 

要充分利用 适用于 JavaScript 的 AWS SDK v3，我们建议使用下面描述的 codemod 脚本。

### 使用 codemod 迁移现有的 v2 代码
<a name="using-codemod"></a>

中的 codemod 脚本集[aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod)有助于将现有的 适用于 JavaScript 的 AWS SDK (v2) 应用程序迁移到使用 v3。 APIs您可以按以下方式运行转换。

```
$ npx aws-sdk-js-codemod -t v2-to-v3 PATH...
```

例如，假设您有以下代码，它用于从 v2 创建一个 Amazon DynamoDB 客户端并调用 `listTables` 运算。

```
// 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);
```

你可以按如下方式对 `example.ts` 运行我们的 `v2-to-v3` 转换。

```
$ 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);
```

我们已经针对常见使用案例实现了转换。如果您的代码无法正确转换，请使用示例输入代码和 observed/expected 输出代码创建[错误报告](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)已经报告了您的特定使用案例，请通过投赞同票表示支持。

## 版本 3 中的新增功能
<a name="welcome_whats_new_v3"></a>

适用于 JavaScript (v3) 的 SDK 版本 3 包含以下新功能。

模块化软件包  
用户现在可以为每项服务使用单独的软件包。

新的中间件堆栈  
用户现在可以使用中间件堆栈来控制操作调用的生命周期。

此外，还编写了 SDK 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)。

## 模块化软件包
<a name="welcome_whats_new_v3_modularized_packages"></a>

适用于 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";
```

### 比较代码大小
<a name="welcome_whats_new_v3_modularized_packages_code_size"></a>

在版本 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 中调用命令
<a name="welcome_whats_new_v3_function_examples"></a>

您可以使用 v2 或 v3 命令在 v3 中执行操作。要使用 v3 命令，请导入命令和所需的 Serv AWS ices 包客户端，然后使用使用 async/await 模式的`.send`方法运行命令。

要使用 v2 命令，请导入所需的 AWS 服务包，然后使用回调或 async/await 模式直接在包中运行 v2 命令。

#### 使用 v3 命令
<a name="using_v3_commands"></a>

v3 为每个 AWS 服务包提供了一组命令，使您能够对该 AWS 服务执行操作。安装 AWS 服务后，您可以浏览项目中 `node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.` 的可用命令 

您必须导入要使用的命令。例如，以下代码可加载 DynamoDB 服务和 `CreateTableCommand` 命令。

```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
```

要按照推荐的 async/await 模式调用这些命令，请使用以下语法。

```
CLIENT.send(new XXXCommand);
```

例如，以下示例使用推荐的模式创建了一个 DynamoDB 表。 async/await 

```
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 命令
<a name="using_v2_commands"></a>

要在 SDK 中使用 v2 命令 JavaScript，请导入完整的 AWS 服务包，如以下代码所示。

```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
```

 要按照推荐的 async/await 模式调用 v2 命令，请使用以下语法。

```
client.command(parameters);
```

以下示例使用 v2 `createTable` 命令使用推荐的模式创建 DynamoDB 表。 async/await 

```
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();
```

## 新的中间件堆栈
<a name="welcome_whats_new_v3_middleware_stack"></a>

借助 SDK 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 之间的区别
<a name="migrate-whats-different"></a>

 本部分介绍了适用于 JavaScript 的 AWS SDK 从 v2 到 v3 版本的主要变更。由于 v3 是对 v2 的模块化重写，因此两者在一些基础概念上存在差异。您可以在我们的[博客文章](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/)中了解这些变更。以下博客文章将帮助您快速入门：
+  [Modular packages in 适用于 JavaScript 的 AWS SDK](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/) 
+  [Introducing Middleware Stack in Modular 适用于 JavaScript 的 AWS SDK](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/) 

 以下是适用于 JavaScript 的 AWS SDK 从 v2 到 v3 的接口更改摘要。其目的是帮助您轻松找到已熟悉的 v2 API 在 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)

# 客户端构造函数
<a name="migrate-client-constructors"></a>

 此列表通过 [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 中支持）。
  +  **v** 3：适用的 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 选项的示例。你可以在的 [v3 API 参考中找到更多信息 NodeHttpHandler](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",
  });
  ```

   如果客户端在浏览器中运行，则可使用另一组选项。你可以在的 [v3 API 参考中找到更多信息 FetchHttpHandler](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**：您可以遵循 [Configuring proxies for 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**：SDK 是否发送异步 HTTP 请求。
    +  **v3**：**已弃用**。请求*始终*为异步。
  +  `xhrWithCredentials` 
    +  **v2**：设置 XMLHttp请求对象的 “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`。在 [v3 API 参考中查看更多信息 RetryInputConfig](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**：是否强制 URLs 使用 S3 对象的路径样式。
  +  **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**：**已弃用**。当区域设置为 `us-east-1` 时，S3 客户端将始终使用区域端点。您可以将区域设置为 `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 已被弃用。v3 *仅*支持签名 v4 AWS。
+  [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 服务中使用加速端点。
  +  **v3**：无变更。

# 凭证提供程序
<a name="migrate-credential-providers"></a>

 在 v2 中，适用于 JavaScript 的 SDK 提供了可供选择的凭证提供程序列表，以及默认在 Node.js 上可用的凭证提供程序链，该链会尝试从所有最常见的提供程序那里加载 AWS 凭证。适用于 JavaScript 的 SDK v3 简化了凭证提供程序的界面，使其更易于使用且更便于编写自定义凭证提供程序。除了新增的凭证提供程序链外，适用于 JavaScript 的 SDK v3 还提供了与 v2 等效的凭证提供程序列表。

 以下是 v2 中的所有凭证提供程序及其在 v3 中的对应等效项。

## 默认凭证提供程序
<a name="default-credential-provider"></a>

 默认凭证提供程序是适用于 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)。

## 临时证书
<a name="temporary-credentials"></a>
+  **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()` 操作获取该角色的凭证。`AWS.ChainableTemporaryCredentials` 与 `AWS.TemporaryCredentials` 在处理 masterCredentials 和刷新方面存在差异。`AWS.ChainableTemporaryCredentials` 通过用户传递的 masterCredentials 刷新已过期的凭证，从而支持 STS 凭证链。然而，`AWS.TemporaryCredentials` 在实例化过程中会以递归方式折叠 masterCredentials，从而阻止了需要中间临时凭证的凭证刷新操作。

   在 v2 中，原始的 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) 已被**弃用**，替换为 `ChainableTemporaryCredentials`。
+  **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)。您可以从 `@aws-sdk/credential-providers` 包中调用 `fromTemporaryCredentials()`。示例如下：

  ```
  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 身份凭证
<a name="cognito-identity-credentials"></a>

 从 Amazon Cognito 身份服务加载凭证，通常在浏览器中使用。
+  **v2**：[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) 表示通过 Amazon Cognito 身份服务从 STS Web 身份联合验证中检索到的凭证。
+  **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)中所述的“简化流程”。“经典流程”*不*支持先调用 `cognito:GetOpenIdToken` 再调用 `sts:AssumeRoleWithWebIdentity` 的操作方式。如果您需要，请向我们提交[功能请求](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）凭证
<a name="ec2-metadataimds-credential"></a>

 表示从 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 凭证
<a name="ecs-credentials"></a>

 表示从指定 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 Container 元数据服务获取凭证。

  ```
  import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
  
  const client = new FooClient({
    credentials: fromContainerMetadata({
      maxRetries: 3, // Optional
      timeout: 0, // Optional
    }),
  });
  ```

## 文件系统凭证
<a name="file-system-credentials"></a>
+ **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 凭证提供程序
<a name="saml-credential-provider"></a>
+  **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=)。

## 共享凭证文件凭证
<a name="shared-credential-file-credentials"></a>

 从共享凭证文件中加载凭证（默认路径为 `~/.aws/credentials`，或由 `AWS_SHARED_CREDENTIALS_FILE` 环境变量定义）。该文件在不同 AWS SDK 和工具中均受支持。更多信息请参阅[共享配置和凭证文件文档](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 身份凭证
<a name="web-identity-credentials"></a>

 使用 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 身份联合验证凭证
<a name="web-identity-federation-credentials"></a>

 从 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 注意事项
<a name="migrate-s3"></a>

## Amazon S3 分段上传
<a name="s3-multipart-upload"></a>

 在 v2 中，Amazon S3 客户端包含一个 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property) 操作，该操作支持利用 [Amazon S3 提供的分段上传功能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html)上传大型对象。

 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
<a name="s3-presigned-url"></a>

 在 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) 操作，用于生成 URL，供用户用来从 Amazon S3 上传或下载对象。

 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 区域重定向
<a name="s3-global-client-region-redirects"></a>

如果向 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 流式传输和缓冲响应
<a name="amazon-s3-stream-vs-buffer"></a>

 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 文档客户端
<a name="migrate-dynamodb-doc-client"></a>

## v3 中 DynamoDB 文档客户端的基本用法
<a name="basic-usage-of-dynamodb-document-client-in-v3"></a>
+  在 v2 中，您可以使用该[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html)类使用数组、数字和对象等 JavaScript 本机类型调用 APIs DynamoDB。这通过将属性值的概念抽象化，简化了 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` 值
<a name="undefined-values-in-when-marshalling"></a>
+  在 v2 中，在对 DynamoDB 进行编组时，对象中的 `undefined` 值会自动被忽略。
+  在 v3 中，`@aws-sdk/lib-dynamodb` 中的默认编组行为已变更：不再省略包含 `undefined` 值的对象。为了与 v2 的功能保持一致，开发人员必须在 DynamoDB 文档客户端的 `marshallOptions` 中将 `removeUndefinedValues` 显式设置为 `true`。

 示例：

```
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) 文件。

# 等待器和签名器
<a name="migrate-waiters-signers"></a>

本页面描述了在适用于 JavaScript 的 AWS SDK v3 中使用等待器和签名器的方法。

## Waiter
<a name="waiters"></a>

 在 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 签名器
<a name="cloudfront-signer"></a>

 在 v2 中，您可以使用 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html) 对请求进行签名，从而访问受限的 Amazon CloudFront 分配。

 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 签名器
<a name="rds-signer"></a>

 在 v2 中，您可以使用 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html) 生成用于 Amazon RDS 数据库的身份验证令牌。

 在 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 签名器
<a name="polly-signer"></a>

 在 v2 中，您可以使用 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html) 为由 Amazon Polly 服务合成的语音生成签名 URL。

 在 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) 程序包中找到。

# 有关特定服务客户端的说明
<a name="migrate-service-client-notes"></a>

## AWS Lambda
<a name="aws-lambda-notes"></a>

 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
<a name="amazon-sqs-notes"></a>

### MD5 校验和
<a name="md5-checksum"></a>

 要跳过对消息正文进行 MD5 校验和计算，请在配置对象上将 `md5` 设置为 *false*。否则，SDK 默认会为发送的消息计算校验和，并验证已检索消息的校验和。

```
// 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 客户端的默认端点。

### 多区域消息
<a name="multi-region-messages"></a>

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

### 自定义终端节点
<a name="custom-endpoint"></a>

 在 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",
});
```

# 补充文档
<a name="migrate-supp-docs"></a>

下表包含补充文档的链接，这些文档将帮助您使用和了解适用于 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 SDK 团队优化 SDK 性能的信息，其中包含配置 SDK 以实现高效运行的技巧。 | 
| [TypeScript](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/TYPESCRIPT.md) | 适用于 JavaScript 的 AWS SDK（v3）相关 TypeScript 技巧和常见问题。 | 
| [错误处理](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）的一般建议。 |