バージョン 2 からのアップグレードAWS SDK for PHP - AWS SDK for PHP

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

バージョン 2 からのアップグレードAWS SDK for PHP

このトピックでは、コードを 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 標準に従っていて、将来は SemVer 標準に従う予定です。

その他の新機能は次のとおりです。

  • サービスクライアントの動作をカスタマイズするためのミドルウェアシステム

  • ページ分割された結果を反復処理するための柔軟なページネーター

  • JMESPath を使用して結果オブジェクトとページネーターオブジェクトからデータをクエリする機能

  • 'debug' 設定オプションによる簡単なデバッグ

分離された HTTP レイヤー

  • デフォルトではリクエストの送信に Guzzle 6 が使用されますが、Guzzle 5 もサポートされています。

  • SDK は、cURL を利用できない環境でも機能します。

  • カスタム HTTP ハンドラーもサポートされています。

非同期リクエスト

  • ウェーターマルチパートアップローダーなどの機能は非同期でも使用できます。

  • promise およびコルーチン を使用して非同期ワークフローを作成できます。

  • 同時処理やバッチ処理されるリクエストのパフォーマンスが向上しました。

バージョン 2 との相違点

プロジェクトの依存関係が更新されました

このバージョンで SDK の依存関係が変更されています。

  • SDK で PHP 5.5 以降が必要になりました。SDK コード内で ジェネレーターを積極的に使用しています。

  • 使用するように SDK をアップグレードしましたGuzzle 6(または 5)、リクエストをに送信するために SDK で使用される、基になる HTTP クライアント実装 (または 5) が提供されます。AWSのサービス。最新バージョンの 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 モデルが実装されていますが、このパッケージではそのパラダイム内でプログラムに機能を提供しています。「」を参照してください。での promiseAWS SDK for PHPバージョン 3詳細については、「」を参照してください。

  • PHP 実装JMESPath(mtdowling/jmespath.php) は SDK では、データクエリ機能を提供するために SDK で使用されます。Aws\Result::search()そしてAws\ResultPaginator::search()方法。「」を参照してください。での JMESPath 式AWS SDK for PHPバージョン 3詳細については、「」を参照してください。

リージョンオプションとバージョンオプションは必須オプションになりました

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

注記

どの API バージョンを使用しているか気にならない場合は、'version' オプションを 'latest' に設定するだけで済みます。ただし、本稼働用のコードでは API バージョン番号を明示的に設定することをお勧めします。

すべてのサービスが利用できるわけではありません。AWS地域。利用可能な AWS リージョンの一覧については、のリージョンとエンドポイントリファレンス。

単一のグローバルエンドポイント (Amazon Route 53 など) 経由でのみ使用できるサービスについては、AWS Identity and Access Management、および Amazon CloudFront) で、設定されたリージョンをに設定してクライアントをインスタンス化します。us-east-1

重要

SDK には、マルチリージョンクライアントも付属しています。マルチリージョンクライアントでは、リクエストをディスパッチできます。AWSパラメータに基づくリージョン (@region) をコマンドパラメータとして指定します。このクライアントでデフォルトで使用されるリージョンは、クライアントコンストラクタで指定する 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() メソッドは引き続き利用できますが、オプションが異なっています。のドキュメントを参照してください。Amazon S3 Transfer ManagerAWS SDK for PHPバージョン 3

    • Aws\S3\Model\ClearBucketAws\S3\Model\DeleteObjectsBatch が、Aws\S3\BatchDeleteS3Client::deleteMatchingObjects() に置き換えられています。

    • のオプションと動作で DynamoDB セッションハンドラーを使用するAWS SDK for PHPバージョン 3少し変わった。

    • Aws\DynamoDb\Model\BatchRequest 名前空間が Aws\DynamoDb\WriteRequestBatch に置き換えられています。「DynamoDB WriteRequestBatch」のドキュメントを参照してください。

    • Aws\Ses\SesClient は、SendRawEmail オペレーションを使用するときに、RawMessage の base64 エンコーディングを処理するようになりました。

  • 削除済み:
    • Amazon DynamoDBItem,Attribute, およびItemIteratorclasses-これらは以前、で廃止されました。バージョン 2.7.0

    • Amazon SNS メッセージバリデータ-これは今です独立した軽量プロジェクトSDK を依存関係として追加する必要はありません。ただし、SDK の phar と ZIP のディストリビューションにはこのプロジェクトが含まれています。「入門ガイド」を参照してください。でAWSPHP 開発ブログ

    • Amazon S3AcpBuilderの とその関連オブジェクトが削除されました。

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.