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

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

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

序章

AWS SDK for PHP バージョン 3 では、SDK の機能を改善するためのかなりの労力のたまものであり、2 年以上にわたるカスタマーフィードバックの取り込み、依存関係のアップグレード、パフォーマンスの改善、最新の PHP 標準の採用を行っています。

バージョン 3 の新機能

AWS SDK for PHP バージョン 3 は PSR-4 標準と PSR-7 標準に従っていて、将来は SemVer 標準に従う予定です。

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

分離された HTTP レイヤー

非同期リクエスト

バージョン 2 との相違点

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

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

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

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

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

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'
]);

クライアント設定が変更されています

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

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'];

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

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

多くの高レベル抽象化が変更されています

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

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

主な相違点:

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

主な相違点:

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