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

のバージョン 2 からの移行 AWS SDK for PHP

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

序章

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

バージョン 3 の新機能

のバージョン 3 は PSR-4 および PSR-7 標準 AWS SDK for PHP に従い、今後は SemVer 標準に従います。

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

分離された HTTP レイヤー

非同期リクエスト

バージョン 2 との違いは何ですか?

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

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

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

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

クライアントのインスタンス化でコンストラクタを使用する

のバージョン 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'
]);

クライアント設定が変更されました

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

Sdk オブジェクト

のバージョン 3 では、 の代替として Aws\Sdk オブジェクト AWS SDK for PHP が導入されています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'];

以下のオペレーションが影響を受け、結果の出力にラップ要素が含まれるようになりました (括弧内は追加されたラップ要素)。

列挙型クラスが削除されました

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 を肥大化せずにその関数を提供できます。

静的ファサードクラスが削除されました

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

ページネーターはイテレーターよりも優先されます

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

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

以下の例は、バージョン 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 式を使用して、より簡単に結果セットからデータを抽出できる メソッドがあります。

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

多くの上位レベルの抽象化が変更されました

全般的に、多くの高レベル抽象化 (クライアントは別として、サービス固有のヘルパーオブジェクト) が改善または更新されています。削除されたものもあります。

SDK の両バージョンからのコードサンプルの比較

次の例は、 のバージョン 3 AWS SDK for PHP を使用する方法がバージョン 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' => '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 から

主な相違点:

<?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";
}

例: グローバル設定でクライアントをインスタンス化する

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 から

主な相違点:

<?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.