本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 Ruby 的 AWS 開發套件入門 了解如何安裝、設定和使用 SDK 來建立 Ruby 應用程式，以程式設計方式存取 AWS 資源。 **Topics** + [使用 驗證 AWS](credentials.md) + [安裝 開發套件](setup-install.md) + [建立簡單的應用程式](hello.md) # AWS 使用適用於 Ruby 的 AWS SDK 透過 驗證 使用 進行開發 AWS 時，您必須建立程式碼向 進行身分驗證的方式 AWS 服務。您可以根據環境和您可用的存取權，以不同的方式設定 AWS 資源的程式設計 AWS 存取。 若要選擇您的身分驗證方法並針對 SDK 進行設定，請參閱 *AWS SDKs和工具參考指南中的*[身分驗證和存取](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。 ## 使用主控台登入資料 針對本機開發，我們建議新使用者使用現有的 AWS 管理主控台登入憑證，以程式設計方式存取 AWS 服務。在瀏覽器型身分驗證之後， AWS 會產生臨時登入資料，以使用本機開發工具，例如 AWS Command Line Interface (AWS CLI) 和 AWS SDK for Ruby。 如果您選擇此方法，請遵循[使用 AWS CLI 使用主控台登入資料進行 AWS 本機開發](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)的說明。 適用於 Ruby 的 AWS SDK 不需要將其他 Gem 套件 （例如 `aws-sdk-signin`) 新增至您的應用程式，即可搭配主控台登入資料使用登入。 ## 使用 IAM Identity Center 身分驗證 如果您選擇此方法，請完成 *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 SDK 和工具參考指南*中的[共用檔案位置](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)設定。這會設定軟體開發套件用於 AWS 請求 AWS 區域 的預設值。此區域用於未指定使用 區域的 SDK 服務請求。 + 開發套件使用描述檔的 [SSO 字符提供者組態](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile)，在傳送請求至 之前取得登入資料 AWS。此`sso_role_name`值是連接至 IAM Identity Center 許可集的 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 ``` 適用於 Ruby 的 AWS SDK 不需要將其他 Gem 套件 （例如 `aws-sdk-sso`和 `aws-sdk-ssooidc`) 新增至您的應用程式，即可使用 IAM Identity Center 身分驗證。 ### 啟動 AWS 存取入口網站工作階段 在執行存取的應用程式之前 AWS 服務，您需要 SDK 的作用中 AWS 存取入口網站工作階段，才能使用 IAM Identity Center 身分驗證來解析登入資料。視您設定的工作階段長度而定，您的存取最終會過期，而且 SDK 會遇到身分驗證錯誤。若要登入 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)資料。 + 若要了解適用於 Ruby 的 AWS SDK 登入資料提供者鏈結，以及 SDK 如何依序自動嘗試不同的身分驗證方法，請參閱 [登入資料提供者鏈結](credential-providers.md#credchain)。 + 如需 AWS SDK 登入資料提供者組態設定，請參閱 SDK *AWS SDKs 和工具參考指南*中的[標準化登入資料提供者](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)。 # 安裝適用於 Ruby 的 AWS SDK 本節包含適用於 Ruby 的 AWS SDK 的先決條件和安裝指示。 ## 先決條件 在使用適用於 Ruby 的 AWS SDK 之前，您必須先向 進行身分驗證 AWS。如需設定身分驗證的資訊，請參閱 [AWS 使用適用於 Ruby 的 AWS SDK 透過 驗證](credentials.md)。 ## 安裝 開發套件 您可以像安裝 Ruby Gem 套件一樣安裝適用於 Ruby 的 AWS SDK。Gem 套件可在 [RubyGems](https://rubygems.org/gems/aws-sdk/) 取得。適用於 Ruby 的 AWS SDK 設計為模組化，並以 分隔 AWS 服務。安裝整個 `aws-sdk` Gem 套件很大，可能需要一個小時的時間。 建議您只為您 AWS 服務 使用的 安裝 Gem 套件。這些名稱命名為 ，`aws-sdk-service_abbreviation`完整清單位於適用於 Ruby README 的 AWS SDK 檔案的[支援服務](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/) + [夏爾比](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 Gem AWS 開發套件： 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 的 AWS SDK 向 Amazon 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 的完整清單，請參閱適用於 Ruby README 檔案的 AWS SDK [支援服務](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 操作，請查看 GitHub 上的[AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/ruby/example_code//s3)。