本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 全局配置 AWS SDKs 和工具 使用 AWS SDKs 和其他 AWS 开发者工具（例如 AWS Command Line Interface (AWS CLI)），您可以与 AWS 服务进行交互 APIs。但是，在尝试执行此操作之前，必须使用执行请求的操作所需的信息来配置 SDK 或工具。 这些信息包含以下各项： + 识别 API 的调用方的**凭证信息**。凭证用于加密向 AWS 服务器发出的请求。使用此信息 AWS 确认您的身份，并可以检索与之相关的权限策略。然后，它可以确定允许您执行哪些操作。 + **其他配置详细信息**，用于告知 AWS CLI 或 SDK 如何处理请求、将请求发送到何处（发送到哪个 AWS 服务端点）以及如何解释或显示响应。 每个 SDK 或工具都支持多个来源，您可以使用这些来源来提供所需的凭证和配置信息。有些来源是 SDK 或工具所独有的，您必须参阅该工具或 SDK 的文档，详细了解如何使用该方法。 但是， AWS SDKs 和工具支持代码本身以外的主要来源的常用设置。本节将介绍以下主题： **Topics** + [使用共享`config`和`credentials`文件进行全局配置 AWS SDKs 和工具](file-format.md) + [查找和更改共享`credentials`文件`config` AWS SDKs 和工具的位置](file-location.md) + [使用环境变量进行全局配置 AWS SDKs 和工具](environment-variables.md) + [使用 JVM 系统属性进行全局配置和 适用于 Java 的 AWS SDK 适用于 Kotlin 的 AWS SDK](jvm-system-properties.md) # 使用共享`config`和`credentials`文件进行全局配置 AWS SDKs 和工具 共享 AWS `config`和`credentials`文件是为 AWS SDK 或工具指定身份验证和配置的最常用方式。 共享的 `config` 和 `credentials` 文件包含一组配置文件。配置文件是一组按键值对组成的配置设置 AWS SDKs，由 AWS Command Line Interface (AWS CLI) 和其他工具使用。将配置值附加到配置文件中，以便配置 SDK/tool 何时使用该配置文件的某些方面。这些文件是 “共享” 的，因为这些值对任何应用程序、进程或 SDKs 对用户的本地环境都有影响。 共享`config`文件和`credentials`文件都是纯文本文件，仅包含 ASCII 字符（UTF-8 编码）。它们采用通常称为 [INI 文件](https://wikipedia.org/wiki/INI_file)的形式。 ## 配置文件 共享文件 `config` 和 `credentials` 中的设置与特定的配置文件相关联。可以在该文件中定义多个配置文件，从而创建将在不同开发环境中应用的不同设置配置。 如果未指定特定的命名 `[default]` 配置文件，则该配置文件包含由 SDK 或工具操作使用的值。您也可以创建单独的配置文件，您可以按名称明确引用这些配置文件。每个配置文件都可以根据应用程序和场景的需要使用不同的设置和值。 **注意** `[default]`只是一个未命名的配置文件。此配置文件之所以命名为`default`，是因为如果用户未指定配置文件，则它是 SDK 使用的默认配置文件。它不为其他配置文件提供接替的默认值。如果您在 `[default]` 配置文件中设置了某些值，但未在命名配置文件中相应设置，则在使用命名配置文件时不会设置该值。 ### 设置命名配置文件 `[default]` 配置文件和多个命名配置文件可以在同一个文件中共存。使用以下设置来选择 SDK 或工具在运行代码时将使用配置文件中的具体设置。此外还可以在代码中或使用 AWS CLI时按命令选择配置文件。 通过设置以下配置之一来配置此功能： **`AWS_PROFILE`-环境变量** 当此环境变量设置为命名配置文件或 “默认” 时，所有 SDK 代码和 AWS CLI 命令都使用该配置文件中的设置。 Linux/macOS 通过命令行设置环境变量的示例： ``` export AWS_PROFILE="my_default_profile_name"; ``` Windows 通过命令行设置环境变量的示例： ``` setx AWS_PROFILE "my_default_profile_name" ``` **`aws.profile`：JVM 系统属性** 对于 JVM 上适用于 Kotlin 的 SDK 和适用于 Java 的 SDK 2.x，您可以[设置 `aws.profile` 系统属性](jvm-system-properties.md#jvm-sys-props-set)。当 SDK 创建服务客户端时，将会使用命名配置文中件的设置，但该设置在代码中被覆盖的情况除外。适用于 Java 的 SDK 1.x 不支持此系统属性。 **注意** 如果应用程序位于运行多个应用程序的服务器上，我们建议您始终使用命名配置文件而不是默认配置文件。环境中的任何 AWS 应用程序都会自动获取默认配置文件，并在它们之间共享。因此，如果其他人更新了其应用程序的默认配置文件，则可能会在无意中影响其他应用程序。为防止出现这种情况，请在共享的 `config` 文件中定义一个命名配置文件，然后在代码中设置该命名配置文件，从而在应用程序中使用该命名配置文件。如果您知道命名配置文件的作用域仅影响您的应用程序，则可以使用环境变量或 JVM 系统属性来设置该命名配置文件。 ## 配置文件的格式 `config` 文件将归入各个节中。节是一个命名的设置集合，它一直持续到遇到另一个节定义行为止。 `config` 文件是使用以下格式的纯文本文件： + 节中的所有条目均采用 `setting-name=value` 的一般形式。 + 可以通过以井号字符 (`#`) 开头来注释掉行。 ### 节类型 节定义是将名称应用于设置集合的行。节定义行以方括号 (`[``]`) 开头和结尾。方括号内有一个节类型标识符和该节的自定义名称。可以使用字母、数字、连字符 (`-`) 和下划线 (`_`)，但不能使用空格。 #### 节类型：`default` 节定义行示例：`[default]` `[default]` 是唯一一个不需要 `profile` 节标识符的配置文件。 下面的示例介绍一个有 `[default]` 配置文件的基本 `config` 文件。它设置了[`region`](feature-region.md)设置。该行之后的所有设置都包含该配置文件中，直到遇到另一个节定义为止。 ``` [default] #Full line comment, this text is ignored. region = us-east-2 ``` #### 节类型：`profile` 节定义行示例：`[profile dev]` `profile` 节定义行是一个您可以应用到不同开发场景的命名配置分组。要更好地了解命名配置文件，请参阅前面关于配置文件的部分。 以下示例展示了一个带有 `profile` 节定义行和命名配置文件 `foo` 的 `config` 文件。该行之后的所有设置都包含该命名配置文件中，直到遇到另一个节定义为止。 ``` [profile foo] ...settings... ``` 某些设置有自己的嵌套子设置组，例如以下示例中的 `s3` 设置和子设置。通过缩进一个或多个空格将子设置与组相关联。 ``` [profile test] region = us-west-2 s3 = max_concurrent_requests=10 max_queue_size=1000 ``` #### 节类型：`sso-session` 节定义行示例：`[sso-session my-sso]` `sso-session`部分定义行命名了一组设置，您使用这些设置来配置配置文件以解析 AWS 凭据 AWS IAM Identity Center。有关配置单点登录身份验证的更多信息，请参阅 [使用 IAM 身份中心对 AWS SDK 和工具进行身份验证](access-sso.md)。配置文件通过键值对链接到 `sso-session` 节，其中 `sso-session` 是密钥，您的 `sso-session` 节名称是值，例如 `sso-session = `。 以下示例配置了一个配置文件，该配置文件将使用 “my-sso” 中的令牌获取 “111122223333SampleRole” 账户中 “” IAM 角色的短期 AWS 证书。在`profile`节中，使用 `sso-session` 密钥按名称引用 “my-sso” `sso-session` 节。 ``` [profile dev] sso_session = my-sso sso_account_id = 111122223333 sso_role_name = SampleRole [sso-session my-sso] sso_region = us-east-1 sso_start_url = https://my-sso-portal.awsapps.com/start ``` #### 节类型：`services` 节定义行示例：`[services dev]` **注意** 该`services`部分支持服务特定的端点自定义，并且仅在包含此功能的工具中 SDKs 可用。要查看此功能是否适用于您的 SDK，请参阅 [Support AWS SDKs by 和工具](feature-ss-endpoints.md#ss-endpoints-sdk-compat) 以了解服务特定的端点。 `services`部分定义行命名了一组为 AWS 服务 请求配置自定义终端节点的设置。配置文件通过键值对链接到 `services` 节，其中 `services` 是密钥，您的 `services` 节名称是值，例如 `services = `。 该`services`部分进一步按` = `行分成小节，其中``是标 AWS 服务 识键。标 AWS 服务 识符基于 API 模型，将所有空格`serviceId`替换为下划线，并将所有字母小写。有关 `services` 节中要使用的所有服务标识符密钥的列表，请参阅[特定于服务的端点的标识符](ss-endpoints-table.md)。服务标识符密钥后面是嵌套的设置，每个设置单独成行，缩进两个空格。 以下示例使用`services`定义来配置端点，使其仅用于向 Amazon DynamoDB 服务发出的请求。在`"local-dynamodb"` `services`节中，使用`services`密钥按名称引用`profile`节。标 AWS 服务 识符密钥是`dynamodb`。 Amazon DynamoDB 服务小节从线路开始`dynamodb = `。后面紧跟的任何缩进行都包含在该小节中，并适用于该服务。 ``` [profile dev] services = local-dynamodb [services local-dynamodb] dynamodb = endpoint_url = http://localhost:8000 ``` 有关自定义端点配置的更多信息，请参阅[特定于服务的端点](feature-ss-endpoints.md)。 ## 凭证文件的格式 `credentials`文件的规则通常与`config`文件的规则相同，唯一的不同是配置文件部分不是以单词`profile`开头。在方括号之间仅使用配置文件名称本身。以下示例展示了一个带有命名配置文件节 `foo` 的 `credentials` 文件。 ``` [foo] ...credential settings... ``` 只有以下被视为“密钥”或敏感的设置才能存储在 `credentials` 文件中：`aws_access_key_id`、`aws_secret_access_key` 和`aws_session_token`。尽管也可以将这些设置放在共享的 `config` 文件中，但我们建议您将这些敏感的值保存在单独的 `credentials` 文件中。这样，如有必要，您可以为每个文件提供单独的权限。 下面的示例介绍一个有 `[default]` 配置文件的基本 `credentials` 文件。它会设置 [`aws_access_key_id`、`aws_secret_access_key` 和 `aws_session_token`](feature-static-credentials.md) 全局设置。 ``` [default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` 无论您在 `credentials` 文件中使用命名配置文件还是“`default`”，此处的任何设置都将与 `config` 文件中具有相同置配文件名称的任何设置合并。如果两个文件中都有共享相同名称的配置文件的凭证，则凭证文件中的密钥优先。 # 查找和更改共享`credentials`文件`config` AWS SDKs 和工具的位置 共享`credentials`文件 AWS `config`和文件是纯文本文件，其中包含 AWS SDKs 和工具的配置信息。这些文件位于您的本地环境中，由 SDK 代码或在该环境中运行的 AWS CLI 命令自动使用。例如，在您自己的计算机上或在 Amazon Elastic Compute Cloud 实例上开发时。 当 SDK 或工具运行时，将会检查这些文件并加载所有可用的配置设置。如果这些文件尚不存在，则 SDK 或工具会自动创建一个基础文件。 默认情况下，这些文件位于您的 `home` 或用户文件夹下名为 `.aws` 的文件夹中。 | 操作系统 | 文件的默认位置和名称 | | --- | --- | | Linux 和 macOS | `~/.aws/config` `~/.aws/credentials` | | Windows | `%USERPROFILE%\.aws\config` `%USERPROFILE%\.aws\credentials` | ## 主目录解析 `~` 仅在下列情况下才用于主目录解析： + 作为路径的开始 + 其后紧接 `/` 或平台特定的分隔符。在 Windows 上，`~/` 和 `~\` 都会解析到主目录。 在确定主目录时，系统会检查以下变量： + （所有平台）`HOME` 环境变量 + （Windows 平台）`USERPROFILE` 环境变量 + （Windows 平台）`HOMEDRIVE` 和 `HOMEPATH` 环境变量的串连（`$HOMEDRIVE$HOMEPATH`） + （可选，根据 SDK 或工具）特定于 SDK 或工具的主路径解析函数或变量 如有可能，如果在路径开头指定了用户的主目录（例如，`~username/`），则会将其解析到请求的用户名的起始目录（例如，`/home/username/.aws/config`）。 ## 更改这些文件的默认位置 您可以使用以下任一方法来覆盖 SDK 或工具加载这些文件的位置。 ### 使用环境变量 可以设置以下环境变量，将这些文件的位置或名称从默认值更改为自定义值： + `config` 文件环境变量：**`AWS_CONFIG_FILE`** + `credentials` 文件环境变量：**`AWS_SHARED_CREDENTIALS_FILE`** ------ #### [ Linux/macOS ] 您可以通过在 Linux 或 macOS 上运行以下[导出](https://linuxconfig.org/learning-linux-commands-export)命令来指定备用位置。 ``` $ export AWS_CONFIG_FILE=/some/file/path/on/the/system/config-file-name $ export AWS_SHARED_CREDENTIALS_FILE=/some/other/file/path/on/the/system/credentials-file-name ``` ------ #### [ Windows ] 您可以通过在 Windows 上运行以下[setx](https://docs.microsoft.com/windows-server/administration/windows-commands/setx)命令来指定备用位置。 ``` C:\> setx AWS_CONFIG_FILE c:\some\file\path\on\the\system\config-file-name C:\> setx AWS_SHARED_CREDENTIALS_FILE c:\some\other\file\path\on\the\system\credentials-file-name ``` ------ 有关使用环境变量配置系统的更多信息，请参阅[使用环境变量进行全局配置 AWS SDKs 和工具](environment-variables.md)。 ### 使用 JVM 系统属性 对于在 JVM 上运行的适用于 Kotlin 的 SDK 以及适用于 Java 的 SDK 2.x，您可以通过设置以下 JVM 系统属性，将这些文件的位置或名称从默认值更改为自定义值： + `config` 文件 JVM 系统属性：**`aws.configFile`** + `credentials` 文件环境变量：**`aws.sharedCredentialsFile`** 有关如何设置 JVM 系统属性的说明，请参阅[如何设置 JVM 系统属性](jvm-system-properties.md#jvm-sys-props-set)。适用于 Java 的 SDK 1.x 不支持这些系统属性。 # 使用环境变量进行全局配置 AWS SDKs 和工具 环境变量提供了另一种在使用和工具时指定配置选项 AWS SDKs 和凭据的方法。环境变量在编写脚本或将某个命名配置文件临时设置为默认配置文件时非常实用。有关大多数支持的环境变量的列表 SDKs，请参阅[环境变量列表](settings-reference.md#EVarSettings)。 **选项的优先顺序** + 如果您使用环境变量来指定设置，则该设置将覆盖从共享 AWS `config`和`credentials`文件中的配置文件加载的任何值。 + 如果您在 AWS CLI 命令行中使用参数来指定设置，则该设置将覆盖配置文件中相应环境变量或配置文件中的任何值。 ## 如何设置环境变量 下面的示例介绍您如何可以为默认用户配置环境变量。 ------ #### [ Linux, macOS, or Unix ] ``` $ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE $ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY $ export AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk $ export AWS_REGION=us-west-2 ``` 设置环境变量会更改使用的值，直到 Shell 会话结束或直到您将该变量设置为其他值。通过在 shell 的启动脚本中设置变量，可使变量在未来的会话中继续有效。 ------ #### [ Windows Command Prompt ] ``` C:\> setx AWS_ACCESS_KEY_ID AKIAIOSFODNN7EXAMPLE C:\> setx AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY C:\> setx AWS_SESSION_TOKEN AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk C:\> setx AWS_REGION us-west-2 ``` 使用 `[set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1)` 设置环境变量会更改使用的值，直到当前命令提示符会话结束，或者直到您将该变量设置为其他值。使用 [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) 设置环境变量会更改当前命令提示符会话和运行该命令后创建的所有命令提示符会话中使用的值。它***不*** 影响在运行该命令时已经运行的其他命令 shell。 ------ #### [ PowerShell ] ``` PS C:\> $Env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" PS C:\> $Env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" PS C:\> $Env:AWS_SESSION_TOKEN="AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk" PS C:\> $Env:AWS_REGION="us-west-2" ``` 如果您在 PowerShell 提示符处设置环境变量（如前面的示例所示），则它只会在当前会话的持续时间内保存该值。要使环境变量设置在所有会话 PowerShell 和命令提示符会话中保持不变，请使用**控制面板**中的**系统**应用程序将其存储。或者，您可以通过将变量添加到您的 PowerShell 个人资料中来为所有将来的 PowerShell 会话设置该变量。有关存储环境变量或跨会话保存环境变量的更多信息，请参阅[PowerShell 文档](https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables)。 ------ ## 无服务器环境变量设置 如果您使用无服务器架构进行开发，则还有其他设置环境变量的选项。根据您的容器，您可以对在这些容器中运行的代码使用不同的策略来查看和访问环境变量，这与非云环境类似。 例如，使用 AWS Lambda，您可以直接设置环境变量。有关详细信息，请参阅《*AWS Lambda 开发人员指南》*中的[使用 AWS Lambda 环境变量](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html)。 在无服务器框架中，通常可在环境设置下的提供者密钥下的 `serverless.yml` 文件中设置 SDK 环境变量。有关该 `serverless.yml` 文件的信息，请参阅无服务器框架文档中的 [ 常规功能设置 ](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#general-function-settings)。 无论您使用哪种机制来设置容器环境变量，都有一些变量由容器保留，例如在 [ 定义的运行时系统环境变量 ](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime) 中为 Lambda 记录的变量。请务必查阅所用容器的官方文档，以确定如何处理环境变量以及是否存在任何限制。 # 使用 JVM 系统属性进行全局配置和 适用于 Java 的 AWS SDK 适用于 Kotlin 的 AWS SDK [JVM 系统属性](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html)提供了另一种方法来指定在 JVM 上运行 SDKs 的配置选项和凭据，例如 适用于 Java 的 AWS SDK 和。 适用于 Kotlin 的 AWS SDK有关支持的 JVM 系统属性的列表 SDKs，请参阅[设置参考](settings-reference.md#JVMSettings)。 **选项的优先顺序** + 如果您使用 JVM 系统属性来指定某个设置，则会覆盖环境变量中找到的或从共享的 AWS `config` 和 `credentials` 文件中加载的任何值。 + 如果您使用环境变量指定某个设置，则会覆盖从共享的 AWS `config` 和 `credentials` 文件中加载的任何值。 ## 如何设置 JVM 系统属性 您可以通过多种方式设置 JVM 系统属性。 ### 通过命令行 使用 `-D` 开关调用 `java` 命令时通过命令行设置 JVM 系统属性。除非在代码中显式覆盖该值，否则以下命令将为所有服务客户端进行 AWS 区域 全局配置。 ``` java -Daws.region=us-east-1 -jar ``` 如果需要设置多个 JVM 系统属性，请多次指定 `-D` 开关。 ### 使用环境变量 如果您无法访问命令行调用 JVM 来运行应用程序，则可以使用 `JAVA_TOOL_OPTIONS` 环境变量来配置命令行选项。这种方法对于在 Java 运行时上运行 AWS Lambda 函数或在嵌入式 JVM 中运行代码等情下非常实用。 除非您在代码中明确覆盖该值，否则以下示例将为所有服务客户端进行 AWS 区域 全局配置。 ------ #### [ Linux, macOS, or Unix ] ``` $ export JAVA_TOOL_OPTIONS="-Daws.region=us-east-1" ``` 设置环境变量会更改使用的值，直到 Shell 会话结束或直到您将该变量设置为其他值。通过在 shell 的启动脚本中设置变量，可使变量在未来的会话中继续有效。 ------ #### [ Windows Command Prompt ] ``` C:\> setx JAVA_TOOL_OPTIONS -Daws.region=us-east-1 ``` 使用 `[set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1)` 设置环境变量会更改使用的值，直到当前命令提示符会话结束，或者直到您将该变量设置为其他值。使用 [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) 设置环境变量会更改当前命令提示符会话和运行该命令后创建的所有命令提示符会话中使用的值。它***不*** 影响在运行该命令时已经运行的其他命令 shell。 ------ ### 在运行时上 您也可以使用以下示例所示的 `System.setProperty` 方法，通过代码在运行时上设置 JVM 系统属性。 ``` System.setProperty("aws.region", "us-east-1"); ``` **重要** 所有 JVM 系统属性都应在初始化 SDK 服务客户端*之前*设置，否则服务客户端可能会使用其他值。