本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 从 Ruby 版 AWS SDK 版本 1 或 2 迁移到 AWS 适用于 Ruby 的 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 开发工具包编写新代码。

## 一般区别
<a name="general-differences"></a>

版本 3 在一个重要方面与版本 2 不同。
+ 每项服务都作为单独的 Gem 提供。

版本 2 在多个重要方面与版本 1 不同。
+ 不同的根命名空间：`Aws` 与 `AWS`。这样可以 side-by-side使用。
+  `Aws.config` – 现在是 vanilla 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 开发工具包将集合和单个资源 getter 分成两个不同的方法：

  ```
  # version 1
  s3.buckets['bucket-name'].objects['key'].delete
  
  # version 2
  s3.bucket('bucket-name').object('key').delete
  ```
+ 批量操作：在版本 1 中，所有批量操作都是手动编码的实用程序。在版本 2 中，许多批量操作是通过 API 自动生成的批处理操作。**版本 2 批处理接口与版本 1 大不相同。**