[适用于 JavaScript 的 Amazon SDK V3 API 参考指南](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/)详细描述了 适用于 JavaScript 的 Amazon SDK 版本 3 (V3) 的所有 API 操作。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 凭证提供程序 在 v2 中，适用于 JavaScript 的 SDK 提供了可供选择的凭证提供程序列表，以及默认在 Node.js 上可用的凭证提供程序链，该链会尝试从所有最常见的提供程序那里加载 Amazon 凭证。适用于 JavaScript 的 SDK v3 简化了凭证提供程序的界面，使其更易于使用且更便于编写自定义凭证提供程序。除了新增的凭证提供程序链外，适用于 JavaScript 的 SDK v3 还提供了与 v2 等效的凭证提供程序列表。 以下是 v2 中的所有凭证提供程序及其在 v3 中的对应等效项。 ## 默认凭证提供程序 默认凭证提供程序是适用于 JavaScript 的 SDK 在您*未*显式提供凭证时解析 Amazon 凭证的方式。 + **v2**：Node.js 中的 [CredentialProviderChain](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html) 按以下顺序从来源解析凭证： + [环境变量](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html) + [共享的凭证文件](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html) + [ECS 容器凭证](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html) + [启动外部进程](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-sourcing-external.html) + [指定文件中的 OIDC 令牌](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html) + [Amazon EC2 实例元数据](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) - 如果上述凭证提供程序之一无法解析 Amazon 凭证，则链将回退至下一个提供程序，直至解析出有效凭证；如果所有提供程序均失败，链将引发错误。 在浏览器和 React Native 运行时中，凭证链为空，凭证必须进行显式设置。 + **v3**：[defaultProvider](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers#fromnodejsproviderchain-1)。凭证来源和回退顺序在 v3 中保持*不变*。它还支持 [Amazon IAM Identity Center 凭证](https://docs.amazonaws.cn/singlesignon/latest/userguide/what-is.html)。 ## 临时证书 + **v2**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html](https://docs.amazonaws.cn/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.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) 已被**弃用**，替换为 `ChainableTemporaryCredentials`。 + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials](https://docs.amazonaws.cn/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 身份凭证 从 Amazon Cognito 身份服务加载凭证，通常在浏览器中使用。 + **v2**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) 表示通过 Amazon Cognito 身份服务从 STS Web 身份联合验证中检索到的凭证。 + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)[`@aws/credential-providers` 程序包](https://www.npmjs.com/package/@aws-sdk/credential-providers)提供了两个凭证提供程序函数：其中一个是 [https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)，接收身份 ID 并调用 `cognitoIdentity:GetCredentialsForIdentity`；另一个是 [https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)，接收身份池 ID，首次调用时先调用 `cognitoIdentity:GetId`，然后调用 `fromCognitoIdentity`。后续调用后者时不会重新调用 GetId。 提供程序实现了 [Amazon Cognito 开发人员指南](https://docs.amazonaws.cn/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）凭证 表示从 Amazon EC2 实例上的元数据服务接收的凭证。 + **v2**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.amazonaws.cn/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.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html) + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.amazonaws.cn/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 }), }); ``` ## 文件系统凭证 + **v2**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html](https://docs.amazonaws.cn/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.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html](https://docs.amazonaws.cn/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` 环境变量定义）。该文件在不同 Amazon SDK 和工具中均受支持。更多信息请参阅[共享配置和凭证文件文档](https://docs.amazonaws.cn/sdkref/latest/guide/creds-config-files.html)。 + **v2**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html) + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.amazonaws.cn/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.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html) + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile](https://docs.amazonaws.cn/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.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html) + **v3**：[https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken](https://docs.amazonaws.cn/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 }, }), }); ```