翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# のバージョン 2 からの移行 AWS SDK for PHP
<a name="getting-started_migration"></a>

このトピックでは、コードを AWS SDK for PHP バージョン 3 に移行する方法、および新しいバージョンと SDK バージョン 2 の相違点について説明します。

**注記**  
SDK の基本的な使用パターン (例: `$result = $client->operation($params);`) はバージョン 2 からバージョン 3 で変更されていないため、スムーズに移行できます。

## 序章
<a name="introduction"></a>

バージョン 3 の AWS SDK for PHP は、SDK の機能の向上、2 年以上にわたる顧客からのフィードバックの組み込み、依存関係のアップグレード、パフォーマンスの向上、最新の PHP 標準の導入に多大な労力を注いでいます。

## バージョン 3 の新機能
<a name="what-s-new-in-version-3"></a>

のバージョン 3 は [PSR-4 および PSR-7 標準](http://php-fig.org) AWS SDK for PHP に従い、今後は [SemVer](http://semver.org/) 標準に従います。

その他の新機能は次のとおりです。
+ サービスクライアントの動作をカスタマイズするためのミドルウェアシステム
+ ページ分割された結果を反復処理するための柔軟な*ページネーター*
+ *JMESPath* を使用して*結果*オブジェクトと*ページネーター*オブジェクトからデータをクエリする機能 
+ `'debug'` 設定オプションによる簡単なデバッグ

### 分離された HTTP レイヤー
<a name="decoupled-http-layer"></a>
+  デフォルトではリクエストの送信に [Guzzle 6](http://guzzlephp.org) が使用されますが、Guzzle 5 もサポートされています。
+ SDK は、cURL を利用できない環境でも機能します。
+ カスタム HTTP ハンドラーもサポートされています。

### 非同期リクエスト
<a name="asynchronous-requests"></a>
+ *ウェーター*や*マルチパートアップローダー*などの機能は非同期でも使用できます。
+ *promise* および*コルーチン* を使用して非同期ワークフローを作成できます。
+ 同時処理やバッチ処理されるリクエストのパフォーマンスが向上しました。

## バージョン 2 との相違点
<a name="what-s-different-from-version-2"></a>

### プロジェクトの依存関係が更新されました
<a name="project-dependencies-are-updated"></a>

このバージョンで SDK の依存関係が変更されています。
+ SDK に PHP 8.1 以降が必要になりました。SDK コード内で [ジェネレーター](http://php.net/manual/en/language.generators.overview.php)を積極的に使用しています。
+ [Guzzle 6](http://guzzlephp.org) (または 5) を使用するように SDK をアップグレードしました。これは、 AWS サービスにリクエストを送信するために SDK が使用する基盤となる HTTP クライアントの実装を提供します。最新バージョンの Guzzle が付属し、非同期リクエスト、スワップ可能な HTTP ハンドラー、PSR-7 準拠、パフォーマンスの向上など、いくつかの改善が行われました。
+ PHP-FIG (`psr/http-message`) による PSR-7 パッケージでは、HTTP リクエスト、HTTP レスポンス、URL、およびストリームを表すためのインターフェイスが定義されています。これらのインターフェイスは SDK と Guzzle 全体で使用されているため、他の PSR-7 準拠パッケージとの相互運用性が提供されています。
+ Guzzle の PSR-7 実装 (`guzzlehttp/psr7`) では、PSR-7 のインターフェイスいくつかの便利なクラスと関数の実装が提供されています。SDK と Guzzle 6 はどちらも、このパッケージに大きく依存しています。
+ Guzzle の [Promises/A\$1](https://promisesaplus.com) 実装 (`guzzlehttp/promises`) は、非同期のリクエストおよびコルーチンを管理するインターフェイスを提供するために、SDK と Guzzle 全体で使用されています。Guzzle のマルチ cURL HTTP ハンドラーでは、非同期リクエストを実現するために最終的にノンブロッキング I/O モデルが実装されていますが、このパッケージではそのパラダイム内でプログラムに機能を提供しています。詳細については[、 AWS SDK for PHP バージョン 3 の Promises ](guide_promises.md)を参照してください。
+ この SDK では、`Aws\Result::search()` および `Aws\ResultPaginator::search()` メソッドでのデータクエリ機能を提供するために、[JMESPath](http://jmespath.org/) の PHP 実装 (`mtdowling/jmespath.php`) が使用されています。詳細については、[AWS SDK for PHP バージョン 3 のJMESPath 式](guide_jmespath.md)」を参照してください。

### リージョンオプションとバージョンオプションは必須オプションになりました
<a name="region-and-version-options-are-now-required"></a>

任意のサービスに対してクライアントをインスタンス化する際に、`'region'` オプションと `'version'` オプションを指定します。バージョン 2 では AWS SDK for PHP、 `'version'`は完全にオプションであり、場合によってはオプション`'region'`でした。バージョン 3 では、どちらも常に必要です。これらのオプションの両方を明確にすることで、コーディング対象の API バージョンと AWS リージョンをロックできます。新しい API バージョンが作成されるか、新しい AWS リージョンが利用可能になると、設定を明示的に更新する準備ができるまで、重大な変更の可能性から分離されます。

**注記**  
どの API バージョンを使用しているか気にならない場合は、`'version'` オプションを `'latest'` に設定するだけで済みます。ただし、本稼働用のコードでは API バージョン番号を明示的に設定することをお勧めします。  
すべての サービスがすべての AWS リージョンで利用できるわけではありません。利用可能なリージョンの一覧については、「[リージョンとエンドポイント](https://docs.aws.amazon.com/general/latest/gr/rande.html)」を参照してください。  
単一のグローバルエンドポイント (Amazon Route 53、 AWS Identity and Access Management、Amazon CloudFront など) 経由でのみ使用できるサービスについては、設定済みリージョンを `us-east-1` に設定してクライアントをインスタンス化します。

**重要**  
SDK には、コマンドパラメータとして指定されたパラメータ (`@region`) に基づいて異なるリージョンにリクエストをディスパッチできるマルチ AWS リージョンクライアントも含まれています。このクライアントでデフォルトで使用されるリージョンは、クライアントコンストラクタで指定する `region` オプションを使用して指定します。

### クライアントのインスタンス化でコンストラクタを使用します
<a name="client-instantiation-uses-the-constructor"></a>

のバージョン 3 では AWS SDK for PHP、クライアントのインスタンス化方法が変更されました。バージョン 2 での `factory` メソッドの代わりに、`new` キーワードを使用するだけでクライアントをインスタンス化できます。

```
use Aws\DynamoDb\DynamoDbClient;

// Version 2 style
$client = DynamoDbClient::factory([
    'region'  => 'us-east-2'
]);

// Version 3 style
$client = new DynamoDbClient([
    'region'  => 'us-east-2',
    'version' => '2012-08-10'
]);
```

**注記**  
`factory()` メソッドを使用したクライアントのインスタンス化も引き続き機能します。ただし、この方法は非推奨と見なされています。

### クライアント設定が変更されています
<a name="client-configuration-has-changed"></a>

のバージョン 3 のクライアント設定オプションは、バージョン 2 から少し変更 AWS SDK for PHP されました。サポートされているすべてのオプションの説明については、[AWS SDK for PHP 「バージョン 3 の設定](guide_configuration.md)」ページを参照してください。

**重要**  
バージョン 3 では、`'key'` と `'secret'` はルートレベルでは有効なオプションではなくなりましたが、`'credentials'` オプションの一部として渡すことはできます。その理由の 1 つは、開発者が AWS 認証情報をプロジェクトにハードコーディングしないようにするためです。

#### Sdk オブジェクト
<a name="the-sdk-object"></a>

のバージョン 3 では、 の代替として `Aws\Sdk` オブジェクト AWS SDK for PHP が導入されています`Aws\Common\Aws`。`Sdk` オブジェクトは、クライアントファクトリとして機能し、複数のクライアント間で共有される設定オプションを管理するために使用されます。

SDK バージョン 2 の `Aws` クラスはサービスロケーター (常に、クライアントの同じインスタンスを返す) のように機能していましたが、バージョン 3 の`Sdk` クラスは、使用されるたびにクライアントの新しいインスタンスを返します。

また、`Sdk` オブジェクトでは、SDK バージョン 2 と同じ設定ファイル形式はサポートされていません。バージョン 2 の設定ファイル形式は、Guzzle 3 固有であったため、廃止されました。設定は、基本的な配列を使用してよりシンプルに行うことができ、詳細については「[Sdk クラスの使用](configuring-service-clients-code.md#sdk-class)」に記載されています。

### 一部の API の結果が変更されています
<a name="some-api-results-have-changed"></a>

SDK が API オペレーション、Amazon ElastiCache、Amazon RDS、および Amazon Redshift の結果を解析する方法に関して一貫性を保つために、一部の API レスポンスにラップ要素が追加されています。

例えば、Amazon RDS の [DescribeEngineDefaultParameters](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeEngineDefaultParameters.html) 呼び出しの結果に、バージョン 3 では「EngineDefaults」ラップ要素が含まれています。この要素はバージョン 2 では存在しませんでした。

```
$client = new Aws\Rds\RdsClient([
    'region'  => 'us-west-1',
    'version' => '2014-09-01'
]);

// Version 2
$result = $client->describeEngineDefaultParameters();
$family = $result['DBParameterGroupFamily'];
$marker = $result['Marker'];

// Version 3
$result = $client->describeEngineDefaultParameters();
$family = $result['EngineDefaults']['DBParameterGroupFamily'];
$marker = $result['EngineDefaults']['Marker'];
```

以下のオペレーションが影響を受け、結果の出力にラップ要素が含まれるようになりました (括弧内は追加されたラップ要素)。
+ Amazon ElastiCache
  + AuthorizeCacheSecurityGroupIngress (CacheSecurityGroup)
  + CopySnapshot (Snapshot)
  + CreateCacheCluster (CacheCluster)
  + CreateCacheParameterGroup (CacheParameterGroup)
  + CreateCacheSecurityGroup (CacheSecurityGroup)
  + CreateCacheSubnetGroup (CacheSubnetGroup)
  + CreateReplicationGroup (ReplicationGroup)
  + CreateSnapshot (Snapshot)
  + DeleteCacheCluster (CacheCluster)
  + DeleteReplicationGroup (ReplicationGroup)
  + DeleteSnapshot (Snapshot)
  + DescribeEngineDefaultParameters (EngineDefaults)
  + ModifyCacheCluster (CacheCluster)
  + ModifyCacheSubnetGroup (CacheSubnetGroup)
  + ModifyReplicationGroup (ReplicationGroup)
  + PurchaseReservedCacheNodesOffering (ReservedCacheNode)
  + RebootCacheCluster (CacheCluster)
  + RevokeCacheSecurityGroupIngress (CacheSecurityGroup)
+ Amazon RDS
  + AddSourceIdentifierToSubscription (EventSubscription)
  + AuthorizeDBSecurityGroupIngress (DBSecurityGroup)
  + CopyDBParameterGroup (DBParameterGroup)
  + CopyDBSnapshot (DBSnapshot)
  + CopyOptionGroup (OptionGroup)
  + CreateDBInstance (DBInstance)
  + CreateDBInstanceReadReplica (DBInstance)
  + CreateDBParameterGroup (DBParameterGroup)
  + CreateDBSecurityGroup (DBSecurityGroup)
  + CreateDBSnapshot (DBSnapshot)
  + CreateDBSubnetGroup (DBSubnetGroup)
  + CreateEventSubscription (EventSubscription)
  + CreateOptionGroup (OptionGroup)
  + DeleteDBInstance (DBInstance)
  + DeleteDBSnapshot (DBSnapshot)
  + DeleteEventSubscription (EventSubscription)
  + DescribeEngineDefaultParameters (EngineDefaults)
  + ModifyDBInstance (DBInstance)
  + ModifyDBSubnetGroup (DBSubnetGroup)
  + ModifyEventSubscription (EventSubscription)
  + ModifyOptionGroup (OptionGroup)
  + PromoteReadReplica (DBInstance)
  + PurchaseReservedDBInstancesOffering (ReservedDBInstance)
  + RebootDBInstance (DBInstance)
  + RemoveSourceIdentifierFromSubscription (EventSubscription)
  + RestoreDBInstanceFromDBSnapshot (DBInstance)
  + RestoreDBInstanceToPointInTime (DBInstance)
  + RevokeDBSecurityGroupIngress (DBSecurityGroup)
+ Amazon Redshift
  + AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup)
  + AuthorizeSnapshotAccess (Snapshot)
  + CopyClusterSnapshot (Snapshot)
  + CreateCluster (Cluster)
  + CreateClusterParameterGroup (ClusterParameterGroup)
  + CreateClusterSecurityGroup (ClusterSecurityGroup)
  + CreateClusterSnapshot (Snapshot)
  + CreateClusterSubnetGroup (ClusterSubnetGroup)
  + CreateEventSubscription (EventSubscription)
  + CreateHsmClientCertificate (HsmClientCertificate)
  + CreateHsmConfiguration (HsmConfiguration)
  + DeleteCluster (Cluster)
  + DeleteClusterSnapshot (Snapshot)
  + DescribeDefaultClusterParameters (DefaultClusterParameters)
  + DisableSnapshotCopy (Cluster)
  + EnableSnapshotCopy (Cluster)
  + ModifyCluster (Cluster)
  + ModifyClusterSubnetGroup (ClusterSubnetGroup)
  + ModifyEventSubscription (EventSubscription)
  + ModifySnapshotCopyRetentionPeriod (Cluster)
  + PurchaseReservedNodeOffering (ReservedNode)
  + RebootCluster (Cluster)
  + RestoreFromClusterSnapshot (Cluster)
  + RevokeClusterSecurityGroupIngress (ClusterSecurityGroup)
  + RevokeSnapshotAccess (Snapshot)
  + RotateEncryptionKey (Cluster)

### Enum クラスが削除されました
<a name="enum-classes-have-been-removed"></a>

 AWS SDK for PHPバージョン 2 に存在していた `Enum` クラスを削除しました (例: `Aws\S3\Enum\CannedAcl`)。Enum は、有効なパラメーター値のグループを表す定数が含まれている、SDK のパブリック API 内の具象クラスでした。これらの列挙値は API バージョンに固有であり、時間の経過とともに変わる可能性があり、PHP の予約語と競合することがあり、あまり便利ではなくなったために、バージョン 3 では削除しました。これらは、バージョン 3 の特性に依存しないデータ駆動型と API バージョンをサポートしています。

`Enum` オブジェクトからの値を使用するのではなく、リテラル値を直接使用します (例: `CannedAcl::PUBLIC_READ` → `'public-read'`)。

### きめ細かな例外クラスが削除されました
<a name="fine-grained-exception-classes-have-been-removed"></a>

各サービスの名前空間に存在していた、きめ細かな例外クラス (例: `Aws\Rds\Exception\{SpecificError}Exception`) を、Enum を削除したのと同様の理由で削除しました。サービスまたはオペレーションによってスローされる例外は、使用されている API バージョンに依存します (バージョン間で変更されることがある)。また、特定のオペレーションでスローされる可能性がある例外の完全な一覧は提供していないため、バージョン 2 のきめ細かな例外クラスは不完全でした。

各サービスのルート例外クラス (例:`Aws\Rds\Exception\RdsException`) をキャッチしてエラーを処理します。例外の `getAwsErrorCode()` メソッドを使用して、特定のエラーコードをチェックできます。これは、別の例外クラスをキャッチするのと機能的には同じですが、SDK を肥大化せずにその関数を提供できます。

### 静的 Facade クラスが削除されました
<a name="static-facade-classes-have-been-removed"></a>

バージョン 2 では AWS SDK for PHP、Laravel にヒントを得た不明瞭な機能があり、 `Aws` クラス`enableFacades()`で を呼び出して、さまざまなサービスクライアントへの静的アクセスを有効にできました。この機能は、PHP のベストプラクティスに反するものであり、ドキュメントに記載するのを 1 年以上前にやめました。バージョン 3 では、この機能は完全に削除されています。`Aws\Sdk` オブジェクトからクライアントオブジェクトを取得して、それを静的クラスとしてではなくオブジェクトインスタンスとして使用します。

### イテレーターはページネーターで置き換えられています
<a name="paginators-supersede-iterators"></a>

のバージョン 2 には、\$1 イテレーター\$1 という機能 AWS SDK for PHP がありました。イテレーターは、ページ分割された結果を反復処理するために使用されるオブジェクトでした。イテレーターに関して、イテレーターでは各結果から特定の値のみが出力されるため、十分な柔軟性がないという苦情がありました。結果内の他の値が必要であっても、イベントリスナーを使用してその値を取得することはできませんでした。

バージョン 3 では、イテレーターは[ページネーター](guide_paginators.md)で置き換えられています。目的は似ていますが、ページネーターの方が柔軟性があります。それは、レスポンスから値ではなく、結果オブジェクトが生成されるためです。

以下の例は、バージョン 2 とバージョン 3 の両方で `S3 ListObjects` オペレーションのページ分割された結果を取得する方法を示すことで、ページネーターがイテレーターとどのように異なるかを示しています。

```
// Version 2
$objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($objects as $object) {
    echo $object['Key'] . "\n";
}
```

```
// Version 3
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($results as $result) {
    // You can extract any data that you want from the result.
    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
}
```

ページネーターオブジェクトには、`search()`JMESPath[ 式を使用して、より簡単に結果セットからデータを抽出できる ](guide_jmespath.md) メソッドがあります。

```
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($results->search('Contents[].Key') as $key) {
    echo $key . "\n";
}
```

**注記**  
バージョン 3 にスムーズに移行できるように、`getIterator()` メソッドは引き続きサポートされていますが、コードを移行してページネーターを使用することをお勧めします。

### 多くの高レベル抽象化が変更されています
<a name="many-higher-level-abstractions-have-changed"></a>

全般的に、多くの高レベル抽象化 (クライアントは別として、サービス固有のヘルパーオブジェクト) が改善または更新されています。削除されたものもあります。
+   
**Updated:**  
  + [Amazon S3 マルチパートアップロード](s3-multipart-upload.md)の使用方法が変更されました。Amazon Glacier マルチパートアップロードも同様の方法で変更されています。
  + [Amazon S3 署名済み URL](s3-presigned-url.md) の作成方法が変更されています。
  + `Aws\S3\Sync` 名前空間が `Aws\S3\Transfer` クラスに置き換えられています。`S3Client::uploadDirectory()` メソッドと `S3Client::downloadBucket()` メソッドは引き続き利用できますが、オプションが異なっています。[AWS SDK for PHP バージョン 3 の Amazon S3 Transfer Manager ](s3-transfer.md)のドキュメントを参照してください。
  +  `Aws\S3\Model\ClearBucket` と `Aws\S3\Model\DeleteObjectsBatch` が、`Aws\S3\BatchDelete` と `S3Client::deleteMatchingObjects()` に置き換えられています。
  + [AWS SDK for PHP バージョン 3 での DynamoDB セッションハンドラーの使用](service_dynamodb-session-handler.md)のオプションと動作が少し変更されました。
  + `Aws\DynamoDb\Model\BatchRequest` 名前空間が `Aws\DynamoDb\WriteRequestBatch` に置き換えられています。「[DynamoDB WriteRequestBatch](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.DynamoDb.WriteRequestBatch.html)」のドキュメントを参照してください。
  + `Aws\Ses\SesClient` は、`SendRawEmail` オペレーションを使用するときに、`RawMessage` の base64 エンコーディングを処理するようになりました。
+   
**削除済み:**  
  + Amazon DynamoDB の `Item`、`Attribute`、`ItemIterator` クラス - これらのクラスは[バージョン 2.7.0](https://github.com/aws/aws-sdk-php/blob/3.0.0/CHANGELOG.md#270===2014-10-08) ですでに非推奨になっています。
  + Amazon SNS メッセージバリデーター - これは、依存関係として SDK を必要としない[個別の軽量プロジェクト](https://github.com/aws/aws-php-sns-message-validator)になりました。ただし、SDK の phar と ZIP のディストリビューションにはこのプロジェクトが含まれています。[AWS PHP 開発ブログに](https://aws.amazon.com/blogs/developer/receiving-amazon-sns-messages-in-php/)入門ガイドがあります。
  + Amazon S3 の `AcpBuilder` とその関連オブジェクトが削除されました。

## SDK の両方のバージョンのサンプルコードの比較
<a name="comparing-code-samples-from-both-versions-of-the-sdk"></a>

 AWS SDK for PHP バージョン 3 での使用方法がバージョン 2 と異なる例を、以下にいくつか示しています。

### 例: Amazon S3 の `ListObjects` オペレーション
<a name="example-s3-listobjects-operation"></a>

#### SDK バージョン 2 から
<a name="from-version-2-of-the-sdk"></a>

```
<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = S3Client::factory([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}
```

#### SDK バージョン 3 から
<a name="from-version-3-of-the-sdk"></a>

主な相違点:
+ クライアントのインスタンス化に `new` ではなく`factory()` を使用します。
+ インストール時に `'version'` と `'region'` オプションが必須です。

```
<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = new S3Client([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1',
    'version' => '2006-03-01'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}
```

### 例: グローバル構成によるクライアントのインスタンス化
<a name="example-instantiating-a-client-with-global-configuration"></a>

#### SDK バージョン 2 から
<a name="id2"></a>

```
<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'default_settings' => array(
            'params' => array(
                'profile' => 'my_profile',
                'region'  => 'us-east-1'
            )
        ),
        'dynamodb' => array(
            'extends' => 'dynamodb',
            'params' => array(
                'region'  => 'us-west-2'
            )
        ),
    )
);
```

```
<?php

require '/path/to/vendor/autoload.php';

use Aws\Common\Aws;

$aws = Aws::factory('path/to/my/config.php');

$sqs = $aws->get('sqs');
// Note: SQS client will be configured for us-east-1.

$dynamodb = $aws->get('dynamodb');
// Note: DynamoDB client will be configured for us-west-2.
```

#### SDK バージョン 3 から
<a name="id3"></a>

主な相違点:
+ `Aws\Common\Aws` ではなく `Aws\Sdk` クラスを使用します。
+ 設定ファイルはありません。代わりに、設定の配列を使用します。
+ インストール時に `'version'` オプションが必須です。
+ `create<Service>()` ではなく `get('<service>')` メソッドを使用します。

```
<?php

require '/path/to/vendor/autoload.php';

$sdk = new Aws\Sdk([
    'profile' => 'my_profile',
    'region' => 'us-east-1',
    'version' => 'latest',
    'DynamoDb' => [
        'region' => 'us-west-2',
    ],
]);

$sqs = $sdk->createSqs();
// Note: Amazon SQS client will be configured for us-east-1.

$dynamodb = $sdk->createDynamoDb();
// Note: DynamoDB client will be configured for us-west-2.
```