本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 從適用於 Ruby 的 AWS SDK 第 1 版或第 2 版遷移至適用於 Ruby 的 AWS SDK 第 3 版
<a name="migrating-to-v3"></a>

本主題包含詳細資訊，可協助您從適用於 Ruby 的 AWS SDK 第 1 版或第 2 版遷移到第 3 版。

## Side-by-side用量
<a name="side-by-side-usage"></a>

您不需要將適用於 Ruby 的 AWS SDK 第 1 版或第 2 版取代為第 3 版。您可以在相同的應用程式中一起使用它們。如需詳細資訊，請參閱[此部落格文章](http://ruby.awsblog.com/post/TxFKSK2QJE6RPZ/Upcoming-Stable-Release-of-AWS-SDK-for-Ruby-Version-2)。

快速範例如下。

```
require 'aws-sdk-v1' # version 1
require 'aws-sdk'    # version 2
require 'aws-sdk-s3' # version 3

s3 = AWS::S3::Client.new # version 1
s3 = Aws::S3::Client.new # version 2 or 3
```

您不需要重寫現有的工作版本 1 或 2 程式碼，即可開始使用版本 3 開發套件。有效的遷移策略是僅針對第 3 版 SDK 撰寫新的程式碼。

## 一般差異
<a name="general-differences"></a>

第 3 版與第 2 版的一個重要方式不同。
+ 每個服務都以個別 Gem 套件的形式提供。

第 2 版與第 1 版有幾個重要的不同。
+ 不同的根命名空間 –`Aws` 相較於 `AWS`。這會啟用side-by-side用量。
+  `Aws.config`– 現在是香草 Ruby 雜湊，而不是方法。
+ 嚴格建構函數選項 - 在版本 1 開發套件中建構用戶端或資源物件時，會忽略未知建構函數選項。在第 2 版中，未知的建構函數選項會觸發 `ArgumentError`。例如：

  ```
  # version 1
  AWS::S3::Client.new(http_reed_timeout: 10)
  # oops, typo'd option is ignored
  
  # version 2
  Aws::S3::Client.new(http_reed_timeout: 10)
  # => raises ArgumentError
  ```

## 用戶端差異
<a name="client-differences"></a>

第 2 版和第 3 版的用戶端類別之間沒有差異。

在版本 1 和版本 2 之間，用戶端類別的外部差異最小。許多服務用戶端在建置用戶端之後都會有相容的介面。一些重要的差異：
+  `Aws::S3::Client` - 第 1 版 Amazon S3 用戶端類別為手動編碼。第 2 版是從服務模型產生。第 2 版中的方法名稱和輸入非常不同。
+  `Aws::EC2::Client`- 第 2 版使用輸出清單的複數名稱，第 1 版使用尾碼 `_set`。例如：

  ```
  # version 1
  resp = AWS::EC2::Client.new.describe_security_groups
  resp.security_group_set
  #=> [...]
  
  # version 2
  resp = Aws::EC2::Client.new.describe_security_groups
  resp.security_groups
  #=> [...]
  ```
+  `Aws::SWF::Client`– 第 2 版使用結構化回應，其中第 1 版使用 Vanilla Ruby 雜湊。
+ 服務類別重新命名 – 第 2 版針對多個服務使用不同的名稱：
  +  `AWS::SimpleWorkflow` 已變成 `Aws::SWF` 
  +  `AWS::ELB` 已變成 `Aws::ElasticLoadBalancing` 
  +  `AWS::SimpleEmailService` 已變成 `Aws::SES` 
+ 用戶端組態選項 – 某些第 1 版組態選項會在第 2 版中重新命名。其他則會移除或取代。以下是主要變更：
  +  `:use_ssl` 已移除。第 2 版會在任何地方使用 SSL。若要停用 SSL，您必須設定使用 `:endpoint`的 `http://`。
  +  `:ssl_ca_file` 現在是 `:ssl_ca_bundle` 
  +  `:ssl_ca_path` 現在是 `:ssl_ca_directory` 
  + 新增了 `:ssl_ca_store`。
  +  `:endpoint` 現在必須是完全合格的 HTTP 或 HTTPS URI，而不是主機名稱。
  + 已移除每個服務`:*_port`的選項，現在已由 取代`:endpoint`。
  +  `:user_agent_prefix` 現在是 `:user_agent_suffix` 

## 資源差異
<a name="resource-differences"></a>

第 2 版和第 3 版中的資源介面之間沒有差異。

第 1 版與第 2 版中的資源介面之間存在顯著差異。第 1 版是完全手動編碼的，其中第 2 版的資源界面是從模型產生。第 2 版的資源界面明顯更一致。一些系統差異包括：
+ 個別的資源類別 – 在第 2 版中，服務名稱是模組，而不是類別。在此模組中，它是資源界面：

  ```
  # version 1
  s3 = AWS::S3.new
  
  # version 2
  s3 = Aws::S3::Resource.new
  ```
+ 參考資源 – 第 2 版 SDK 將集合和個別資源取得器分成兩種不同的方法：

  ```
  # version 1
  s3.buckets['bucket-name'].objects['key'].delete
  
  # version 2
  s3.bucket('bucket-name').object('key').delete
  ```
+ 批次操作 – 在第 1 版中，所有批次操作都是手動編碼的公用程式。在第 2 版中，許多批次操作都是透過 API 自動產生的批次操作。**第 2 版批次處理介面與第 1 版非常不同。**