翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS SDK for PHP のバージョン 2 からのアップグレード
このトピックでは、コードを AWS SDK for PHP バージョン 3 に移行する方法、および新しいバージョンと SDK バージョン 2 の相違点について説明します。
注記
SDK の基本的な使用パターン (例: $result = $client->operation($params);
) はバージョン 2 からバージョン 3 で変更されていないため、スムーズに移行できます。
序章
AWS SDK for PHP バージョン 3 では、SDK の機能を改善するためのかなりの労力のたまものであり、2 年以上にわたるカスタマーフィードバックの取り込み、依存関係のアップグレード、パフォーマンスの改善、最新の PHP 標準の採用を行っています。
バージョン 3 の新機能
AWS SDK for PHP バージョン 3 は PSR-4 標準と PSR-7 標準
その他の新機能は次のとおりです。
-
サービスクライアントの動作をカスタマイズするためのミドルウェアシステム
-
ページ分割された結果を反復処理するための柔軟なページネーター
-
JMESPath を使用して結果オブジェクトとページネーターオブジェクトからデータをクエリする機能
-
'debug'
設定オプションによる簡単なデバッグ
分離された HTTP レイヤー
-
デフォルトではリクエストの送信に Guzzle 6
が使用されますが、Guzzle 5 もサポートされています。 -
SDK は、cURL を利用できない環境でも機能します。
-
カスタム HTTP ハンドラーもサポートされています。
非同期リクエスト
-
ウェーターやマルチパートアップローダーなどの機能は非同期でも使用できます。
-
promise およびコルーチン を使用して非同期ワークフローを作成できます。
-
同時処理やバッチ処理されるリクエストのパフォーマンスが向上しました。
バージョン 2 との相違点
プロジェクトの依存関係が更新されました
このバージョンで SDK の依存関係が変更されています。
-
SDK で PHP 5.5 以降が必要になりました。SDK コード内で ジェネレーター
を積極的に使用しています。 -
Guzzle 6
(または 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+
実装 ( guzzlehttp/promises
) は、非同期のリクエストおよびコルーチンを管理するインターフェイスを提供するために、SDK と Guzzle 全体で使用されています。Guzzle のマルチ cURL HTTP ハンドラーでは、非同期リクエストを実現するために最終的にノンブロッキング I/O モデルが実装されていますが、このパッケージではそのパラダイム内でプログラムに機能を提供しています。詳細については、「AWS SDK for PHP バージョン 3 での promise」を参照してください。 -
この SDK では、
Aws\Result::search()
およびAws\ResultPaginator::search()
メソッドでのデータクエリ機能を提供するために、JMESPathの PHP 実装 ( mtdowling/jmespath.php
) が使用されています。詳細については、「AWS SDK for PHP バージョン 3 での JMESPath 式」を参照してください。
リージョンオプションとバージョンオプションは必須オプションになりました
任意のサービスに対してクライアントをインスタンス化する際に、'region'
オプションと 'version'
オプションを指定します。AWS SDK for PHP バージョン 2 では、'version'
は完全に省略可能であり、'region'
は場合によって省略可能でした。バージョン 3 では、どちらも常に必要です。これらのオプションの両方を明示的に指定することによって、コーディングしている API バージョンと AWS リージョンに縛りつけることができます。新しい API バージョンが作成された場合や新しい AWS リージョンが利用可能になった場合に、ユーザーが設定を明示的に更新する準備が整うまでは、互換性を破る可能性がある変更の影響を受けなくなります。
注記
どの API バージョンを使用しているか気にならない場合は、'version'
オプションを 'latest'
に設定するだけで済みます。ただし、本稼働用のコードでは API バージョン番号を明示的に設定することをお勧めします。
すべての AWS リージョンですべてのサービスを利用できるわけではありません。利用可能なリージョンの一覧については、「リージョンとエンドポイント」を参照してください。
単一のグローバルエンドポイント (Amazon Route 53、AWS Identity and Access Management、Amazon CloudFront など) 経由でのみ使用できるサービスについては、設定済みリージョンを us-east-1
に設定してクライアントをインスタンス化します。
重要
SDK には、マルチリージョンクライアントも付属しています。マルチリージョンクライアントでは、コマンドラインパラメーターとして指定されたパラメータ (@region
) に基づいて、異なる AWS リージョンにリクエストをディスパッチできます。このクライアントでデフォルトで使用されるリージョンは、クライアントコンストラクタで指定する region
オプションを使用して指定します。
クライアントのインスタンス化でコンストラクタを使用します
AWS SDK for PHP バージョン 3 では、クライアントをインスタンス化する方法が変更されています。バージョン 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()
メソッドを使用したクライアントのインスタンス化も引き続き機能します。ただし、この方法は非推奨と見なされています。
クライアント設定が変更されています
AWS SDK for PHP バージョン 3 でのクライアント設定オプションは、バージョン 2 から少し変更されています。サポートされているすべてのオプションの説明については、「AWS SDK for PHP バージョン 3 の設定」ページを参照してください。
重要
バージョン 3 では、'key'
と 'secret'
はルートレベルでは有効なオプションではなくなりましたが、'credentials'
オプションの一部として渡すことはできます。この変更の 1 つの理由は、デベロッパーがプロジェクト内で AWS 認証情報をハードコーディングしないようにするためです。
Sdk オブジェクト
AWS SDK for PHP バージョン 3 では、Aws\Sdk
オブジェクトが Aws\Common\Aws
の置き換えとして導入されています。Sdk
オブジェクトは、クライアントファクトリとして機能し、複数のクライアント間で共有される設定オプションを管理するために使用されます。
SDK バージョン 2 の Aws
クラスはサービスロケーター (常に、クライアントの同じインスタンスを返す) のように機能していましたが、バージョン 3 のSdk
クラスは、使用されるたびにクライアントの新しいインスタンスを返します。
また、Sdk
オブジェクトでは、SDK バージョン 2 と同じ設定ファイル形式はサポートされていません。バージョン 2 の設定ファイル形式は、Guzzle 3 固有であったため、廃止されました。設定は、基本的な配列を使用してよりシンプルに行うことができ、詳細については「Sdk クラスの使用」に記載されています。
一部の API の結果が変更されています
SDK が API オペレーション、Amazon ElastiCache、Amazon RDS、および Amazon Redshift の結果を解析する方法に関して一貫性を保つために、一部の API レスポンスにラップ要素が追加されています。
例えば、Amazon RDS の DescribeEngineDefaultParameters 呼び出しの結果に、バージョン 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 クラスが削除されました
AWS SDK for PHP バージョン 2 に存在していた Enum
クラスを削除しました (例: Aws\S3\Enum\CannedAcl
)。Enum は、有効なパラメーター値のグループを表す定数が含まれている、SDK のパブリック API 内の具象クラスでした。これらの列挙値は API バージョンに固有であり、時間の経過とともに変わる可能性があり、PHP の予約語と競合することがあり、あまり便利ではなくなったために、バージョン 3 では削除しました。これらは、バージョン 3 の特性に依存しないデータ駆動型と API バージョンをサポートしています。
Enum
オブジェクトからの値を使用するのではなく、リテラル値を直接使用します (例: CannedAcl::PUBLIC_READ
→ 'public-read'
)。
きめ細かな例外クラスが削除されました
各サービスの名前空間に存在していた、きめ細かな例外クラス (例: Aws\Rds\Exception\{SpecificError}Exception
) を、Enum を削除したのと同様の理由で削除しました。サービスまたはオペレーションによってスローされる例外は、使用されている API バージョンに依存します (バージョン間で変更されることがある)。また、特定のオペレーションでスローされる可能性がある例外の完全な一覧は提供していないため、バージョン 2 のきめ細かな例外クラスは不完全でした。
各サービスのルート例外クラス (例:Aws\Rds\Exception\RdsException
) をキャッチしてエラーを処理します。例外の getAwsErrorCode()
メソッドを使用して、特定のエラーコードをチェックできます。これは、別の例外クラスをキャッチするのと機能的には同じですが、SDK を肥大化せずにその関数を提供できます。
静的 Facade クラスが削除されました
AWS SDK for PHP バージョン 2 には、Aws
クラスで enableFacades()
を呼び出して各種サービスクライアントへの静的アクセスを有効にできる、Laravel から着想されたわかりにくい機能がありました。この機能は、PHP のベストプラクティスに反するものであり、ドキュメントに記載するのを 1 年以上前にやめました。バージョン 3 では、この機能は完全に削除されています。Aws\Sdk
オブジェクトからクライアントオブジェクトを取得して、それを静的クラスとしてではなくオブジェクトインスタンスとして使用します。
イテレーターはページネーターで置き換えられています
AWS SDK for PHP バージョン 2 には「イテレーター」という機能がありました。イテレーターは、ページ分割された結果を反復処理するために使用されるオブジェクトでした。イテレーターに関して、イテレーターでは各結果から特定の値のみが出力されるため、十分な柔軟性がないという苦情がありました。結果内の他の値が必要であっても、イベントリスナーを使用してその値を取得することはできませんでした。
バージョン 3 では、イテレーターはページネーターで置き換えられています。目的は似ていますが、ページネーターの方が柔軟性があります。それは、レスポンスから値ではなく、結果オブジェクトが生成されるためです。
以下の例は、バージョン 2 とバージョン 3 の両方で S3 ListObjects
オペレーションのページ分割された結果を取得する方法を示すことで、ページネーターがイテレーターとどのように異なるかを示しています。
// Version 2 $objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($objects as $object) { echo $object['Key'] . "\n"; }
// Version 3 $results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-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 式を使用して、より簡単に結果セットからデータを抽出できる メソッドがあります。
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results->search('Contents[].Key') as $key) { echo $key . "\n"; }
注記
バージョン 3 にスムーズに移行できるように、getIterator()
メソッドは引き続きサポートされていますが、コードを移行してページネーターを使用することをお勧めします。
多くの高レベル抽象化が変更されています
全般的に、多くの高レベル抽象化 (クライアントは別として、サービス固有のヘルパーオブジェクト) が改善または更新されています。削除されたものもあります。
-
- Updated:
-
-
Amazon S3 マルチパートアップロードの使用方法が変更されました。Amazon S3 Glacier マルチパートアップロードも同様の方法で変更されています。
-
Amazon S3 署名済み URL の作成方法が変更されています。
-
Aws\S3\Sync
名前空間がAws\S3\Transfer
クラスに置き換えられています。S3Client::uploadDirectory()
メソッドとS3Client::downloadBucket()
メソッドは引き続き利用できますが、オプションが異なっています。「AWS SDK for PHP バージョン 3 での Amazon S3 Transfer Manager」のドキュメントを参照してください。 -
Aws\S3\Model\ClearBucket
とAws\S3\Model\DeleteObjectsBatch
が、Aws\S3\BatchDelete
とS3Client::deleteMatchingObjects()
に置き換えられています。 -
「AWS SDK for PHP バージョン 3 での DynamoDB セッションハンドラーの使用」で説明しているオプションと動作が多少変更されています。
-
Aws\DynamoDb\Model\BatchRequest
名前空間がAws\DynamoDb\WriteRequestBatch
に置き換えられています。「DynamoDB WriteRequestBatch」のドキュメントを参照してください。 -
Aws\Ses\SesClient
は、SendRawEmail
オペレーションを使用するときに、RawMessage
の base64 エンコーディングを処理するようになりました。
-
-
- 削除済み:
-
-
Amazon DynamoDB の
Item
、Attribute
、ItemIterator
クラス - これらのクラスはバージョン 2.7.0ですでに非推奨になっています。 -
Amazon SNS メッセージバリデーター - これは、依存関係として SDK を必要としない個別の軽量プロジェクト
になりました。ただし、SDK の phar と ZIP のディストリビューションにはこのプロジェクトが含まれています。AWS PHP 開発ブログ に、このプロジェクトの入門ガイドがあります。 -
Amazon S3 の
AcpBuilder
とその関連オブジェクトが削除されました。
-
SDK の両方のバージョンのサンプルコードの比較
AWS SDK for PHP バージョン 3 での使用方法がバージョン 2 と異なる例を、以下にいくつか示しています。
例: Amazon S3 ListObjects オペレーション
SDK バージョン 2 から
<?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' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }
SDK バージョン 3 から
主な相違点:
-
クライアントのインスタンス化に
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' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }
例: グローバル構成によるクライアントのインスタンス化
SDK バージョン 2 から
<?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 から
主な相違点:
-
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.