本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 适用于 Ruby 的 AWS SDK 入门 了解如何安装、设置和使用 SDK 创建 Ruby 应用程序，以便以编程方式访问 AWS 资源。 **Topics** + [使用进行身份验证 AWS](credentials.md) + [安装 SDK](setup-install.md) + [创建简单的应用程序](hello.md) # AWS 使用 AWS 适用于 Ruby 的 SDK 进行身份验证 使用开发 AWS 时，您必须确定您的代码是如何进行身份验证的。 AWS 服务您可以根据环境和可用的访问权限以不同的方式配置对 AWS 资源的编程 AWS 访问权限。 要选择您的身份验证方法并针对 SDK 进行配置，请参阅[和*工具参考指南中的身份验证AWS SDKs 和*访问](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。 ## 使用控制台凭证 对于本地开发，我们建议新用户使用其现有的 AWS 管理控制台登录凭证以编程方式访问 AWS 服务。基于浏览器的身份验证后， AWS 生成可与 AWS 命令行界面 (CL AWS I) 和 AWS SDK for Ruby 等本地开发工具配合使用的临时证书。 如果您选择此方法，请按照说明使用 [AWS CLI 使用控制台凭据登录进行 AWS 本地开发](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)。 AWS 适用于 Ruby 的 SDK 无需向应用程序中添加额外的 gem（例如`aws-sdk-signin`）即可使用控制台凭据登录。 ## 使用 IAM 身份中心身份验证 如果您选择此方法，请完成*AWS SDKs 和工具参考指南*[中的 IAM Identity Center 身份验证](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html)程序。此后，您的环境应包含以下元素： + AWS CLI，用于在运行应用程序之前启动 AWS 访问门户会话。 + [共享 AWS`config` 文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)，其 `[default]` 配置文件包含一组可从 SDK 中引用的配置值。要查找此文件的位置，请参阅*AWS SDKs 和工具参考指南*中的[共享文件的位置](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)。 + 共享 `config` 文件设置了 [https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) 设置。这将设置 SDK 用于 AWS 请求的默认值 AWS 区域 。此区域用于未指定使用区域的 SDK 服务请求。 + 在向 AWS发送请求之前，SDK 使用配置文件的 [SSO 令牌提供程序配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile)来获取凭证。该`sso_role_name`值是与 IAM 身份中心权限集关联的 IAM 角色，允许访问您的应用程序中的用户。 AWS 服务 以下示例 `config` 文件展示了使用 SSO 令牌提供程序配置来设置的默认配置文件。配置文件的 `sso_session` 设置是指所指定的 [`sso-session` 节](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session)。该`sso-session`部分包含启动 AWS 访问门户会话的设置。 ``` [default] sso_session = my-sso sso_account_id = 111122223333 sso_role_name = SampleRole region = us-east-1 output = json [sso-session my-sso] sso_region = us-east-1 sso_start_url = https://provided-domain.awsapps.com/start sso_registration_scopes = sso:account:access ``` AWS 适用于 Ruby 的 SDK 无需向您的应用程序添加额外的 gem（例如`aws-sdk-sso`和`aws-sdk-ssooidc`）即可使用 IAM 身份中心身份验证。 ### 启动 AWS 访问门户会话 在运行可访问的应用程序之前 AWS 服务，您需要为开发工具包进行有效的 AWS 访问门户会话，才能使用 IAM Identity Center 身份验证来解析证书。根据配置的会话时长，访问权限最终将过期，并且开发工具包将遇到身份验证错误。要登录 AWS 访问门户，请在中运行以下命令 AWS CLI。 ``` aws sso login ``` 如果遵循引导并具有默认的配置文件设置，则无需使用 `--profile` 选项来调用该命令。如果您的 SSO 令牌提供程序配置在使用指定的配置文件，则命令为 `aws sso login --profile named-profile`。 要选择性测试是否已有活动会话，请运行以下 AWS CLI 命令。 ``` aws sts get-caller-identity ``` 如果会话是活动的，则对此命令的响应会报告共享 `config` 文件中配置的 IAM Identity Center 账户和权限集。 **注意** 如果您已经有一个有效的 AWS 访问门户会话并且`aws sso login`正在运行，则无需提供凭据。 登录过程可能会提示您允许 AWS CLI 访问您的数据。由于 AWS CLI 是在适用于 Python 的 SDK 之上构建的，因此权限消息可能包含`botocore`名称的变体。 ## 更多身份验证信息 人类用户，也称为*人类身份*，是应用程序的人员、管理员、开发人员、操作员和使用者。他们必须具有身份才能访问您的 AWS 环境和应用程序。作为组织成员的人类用户（即您、开发人员）也称为*工作人员身份*。 访问时使用临时证书 AWS。您可以为人类用户使用身份提供商，通过扮演提供临时证书的角色来提供对 AWS 账户的联合访问权限。对于集中式访问权限管理，我们建议使用 AWS IAM Identity Center (IAM Identity Center) 来管理对您账户的访问权限以及这些账户中的其他权限。有关更多替代方案，请参阅以下内容： + 有关最佳实践的更多信息，请参阅《IAM 用户指南》**中的 [IAM 中的安全最佳实践](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。 + 要创建短期 AWS 证书，请参阅 *IAM 用户指南*中的[临时安全证书](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。 + 要了解 AWS SDK for Ruby 凭证提供程序链，以及 SDK 如何按顺序自动尝试不同的身份验证方法，请参阅[凭证提供程序链](credential-providers.md#credchain)。 + 有关 AWS SDK 凭据提供商的配置设置，请参阅《*工具参考*指南》AWS SDKs 中的[标准化凭据提供程序](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)。 # 安装适用于 Ruby 的 S AWS DK 此部分包括针对适用于 Ruby 的 AWS SDK 的先决条件和安装说明。 ## 先决条件 在使用适用于 Ruby 的 AWS SDK 之前，必须使用进行身份验证 AWS。有关设置身份验证的信息，请参阅[AWS 使用 AWS 适用于 Ruby 的 SDK 进行身份验证](credentials.md)。 ## 安装 SDK 你可以像安装任何 Ruby gem 一样安装适用于 Ruby 的 AWS SDK。这些宝石可在以下网址购买[RubyGems](https://rubygems.org/gems/aws-sdk/)。 AWS 适用于 Ruby 的 SDK 采用模块化设计，并由以下部分隔开 AWS 服务。整个 `aws-sdk` Gem 较大，安装过程可能需要一个多小时。 我们建议仅安装供 AWS 服务 您使用的宝石。它们命名为 like`aws-sdk-service_abbreviation`，完整列表可在 AWS SDK for Ruby 自述文件的 “[支持的服务](https://github.com/aws/aws-sdk-ruby/#supported-services)” 表中找到。例如，用于与 Amazon S3 服务交互的 Gem 可直接从 [https://rubygems.org/gems/aws-sdk-s3](https://rubygems.org/gems/aws-sdk-s3) 中获得。 ### Ruby 版本管理器 我们建议不要使用系统 Ruby，而是使用如下所示的 Ruby 版本管理器： + [RVM](http://rvm.io/) + [chruby](https://github.com/postmodern/chruby) + [rbenv](https://github.com/rbenv/rbenv) 例如，如果您使用的是 Amazon Linux 2 操作系统，则可以使用以下命令更新 RVM，列出可用的 Ruby 版本，然后选择要使用适用于 Ruby 的 AWS SDK 进行开发的版本。所需的最低 Ruby 版本为 2.5。 ``` $ rvm get head $ rvm list known $ rvm install ruby-3.1.3 $ rvm --default use 3.1.3 ``` ### Bundler 如果你使用 [Bundler](http://bundler.io/)，则使用以下命令安装适用于 Amazon S3 的 Ruby S AWS DK gem： 1. 安装 Bundler 并创建 `Gemfile`： ``` $ gem install bundler $ bundle init ``` 1. 打开创建`Gemfile`的，为你的代码将使用的每个 AWS 服务 Gem 添加一`gem`行。要按照 Amazon S3 示例进行操作，请将以下行添加到文件底部： ``` gem "aws-sdk-s3" ``` 1. 保存 Gemfile。 1. 安装 `Gemfile` 中指定的依赖项： ``` $ bundle install ``` # 使用适用于 Ruby 的 AWS SDK 创建简单应用程序 使用适用于 Ruby 的 S AWS DK 向亚马逊 S3 打个招呼。以下示例显示了 Amazon S3 存储桶的列表。 ## 编写代码 复制并在新的源文件中粘贴以下代码。将文件命名为 `hello-s3.rb`。 ``` require 'aws-sdk-s3' # Wraps Amazon S3 resource actions. class BucketListWrapper attr_reader :s3_resource # @param s3_resource [Aws::S3::Resource] An Amazon S3 resource. def initialize(s3_resource) @s3_resource = s3_resource end # Lists buckets for the current account. # # @param count [Integer] The maximum number of buckets to list. def list_buckets(count) puts 'Found these buckets:' @s3_resource.buckets.each do |bucket| puts "\t#{bucket.name}" count -= 1 break if count.zero? end true rescue Aws::Errors::ServiceError => e puts "Couldn't list buckets. Here's why: #{e.message}" false end end # Example usage: def run_demo wrapper = BucketListWrapper.new(Aws::S3::Resource.new) wrapper.list_buckets(25) end run_demo if $PROGRAM_NAME == __FILE__ ``` AWS 适用于 Ruby 的 SDK 采用模块化设计，并采用以下方式分隔 AWS 服务。安装 Gem 后，Ruby 源文件顶部的 `require` 语句会导入 Amazon S3 服务的 AWS SDK 类和方法。有关可用 AWS 服务 gem 的完整列表，请参阅 AWS SDK for Ruby README 文件的 “[支持的服务](https://github.com/aws/aws-sdk-ruby/#supported-services)” 表。 ``` require 'aws-sdk-s3' ``` ## 运行程序 打开命令提示符以运行 Ruby 程序。用于运行 Ruby 程序的典型命令语法是： ``` ruby [source filename] [arguments...] ``` 此示例代码不使用任何参数。要运行此代码，请在命令提示符下输入以下内容： ``` $ ruby hello-s3.rb ``` ## Windows 用户的注意事项 在 Windows 上使用 SSL 证书并运行 Ruby 代码时，您可能会看到类似如下的错误。 ``` C:\Ruby>ruby buckets.rb C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `connect': SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed (Seahorse::Client::NetworkingError) from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `block in connect' from C:/Ruby200-x64/lib/ruby/2.0.0/timeout.rb:66:in `timeout' from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:921:in `connect' from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:862:in `do_start' from C:/Ruby200-x64/lib/ruby/2.0.0/net/http.rb:857:in `start' ... ``` 要修复此问题，请在第一次 AWS 调用之前将以下行添加到 Ruby 源文件中。 ``` Aws.use_bundled_cert! ``` 如果您在 Ruby 程序中只使用 `aws-sdk-s3` Gem，并且想要使用捆绑证书，则还需要添加 `aws-sdk-core` Gem。 ## 后续步骤 要测试许多其他 Amazon S3 操作，请查看上的 “[AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/ruby/example_code//s3)” GitHub。