AWS SDK for PHP バージョン 3 の基本的な使用パターン - AWS SDK for PHP
前提条件コードで SDK をインクルードする使用法の概要クライアントの作成Sdk クラスの使用サービスオペレーションの実行非同期リクエスト結果オブジェクトの使用エラー処理

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

AWS SDK for PHP バージョン 3 の基本的な使用パターン

このトピックでは、 AWS SDK for PHPの基本的な使用パターンについて説明します。

前提条件

コードで SDK をインクルードする

どのような手法で SDK でインストールにしたかにかかわらず、1 つの require ステートメントだけで SDK をインクルードできます。インストール手法に最適な PHP コードについては、次の表を参照してください。/path/to/ は、使用しているシステムでの実際のパスに置き換えます。

インストール手法 require ステートメント

Composer の使用

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

phar の使用

require '/path/to/aws.phar';

ZIP の使用

require '/path/to/aws-autoloader.php';

このトピックでは、Composer のインストール方法を示します。別のインストール方法を使用している場合は、このセクションを参照して適切な require コードを見つけてください。

使用法の概要

SDK を使用して AWS サービスとやり取りするには、クライアントオブジェクトをインスタンス化します。クライアントオブジェクトには、サービスの API のオペレーションと対応するメソッドがあります。特定のオペレーションを実行するには、それに対応するメソッドを呼び出します。そのメソッドでは、成功すると配列に類似した Result オブジェクトが返され、失敗すると 例外がスローされます。

クライアントの作成

クライアントのコンストラクタにオプションの連想配列を渡すことによって、クライアントを作成できます。

インポート 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

サンプルコード 

//Create an S3Client
$s3 = new Aws\S3\S3Client([
    'region' => 'us-east-2'  // Since version 3.277.10 of the SDK,
]);                          // the 'version' parameter defaults to 'latest'.

オプションの「version」パラメーターに関する情報は、「設定オプション」のトピックに記載されています。

このクライアントには明示的に認証情報を指定していないことがわかります。これは、SDK がデフォルトの認証情報プロバイダーチェーンを使用して認証情報を検索するためです。

すべての一般的なクライアント設定オプションについては、「AWS SDK for PHP バージョン 3 の設定」で詳しく説明されています。クライアントに指定されるオプションの配列は、作成するクライアントによって異なります。これらのカスタムクライアント設定オプションについては、各クライアントの API ドキュメントで説明されています。

Sdk クラスの使用

Aws\Sdk クラスは、クライアントファクトリとして機能し、複数のクライアント間で共有される設定オプションを管理するために使用されます。特定のクライアントコンストラクタに指定できる多くのオプションを、Aws\Sdk クラスに対しても指定できます。それらのオプションは、各クライアントコンストラクタにも適用されます。

インポート 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

サンプルコード 

// The same options that can be provided to a specific client constructor can also be supplied to the Aws\Sdk class.
// Use the us-west-2 region and latest version of each client.
$sharedConfig = [
    'region' => 'us-west-2'
];
// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);
// Create an Amazon S3 client using the shared configuration data.
$client = $sdk->createS3();

すべてのクライアント間で共有されるオプションは、ルートレベルのキーと値のペアに配置されます。サービス固有の設定データは、サービスの名前空間 (「S3」、「DynamoDb」など) と同じキーで指定できます。

$sdk = new Aws\Sdk([
    'region'   => 'us-west-2',
    'DynamoDb' => [
        'region' => 'eu-central-1'
    ]
]);

// Creating an Amazon DynamoDb client will use the "eu-central-1" AWS Region
$client = $sdk->createDynamoDb();

サービス固有の設定値は、サービス固有の値とルートレベルの値の共用体です (つまり、サービス固有の値がルートレベルの値にシャローマージされている)。

注記

アプリケーションでクライアントの複数のインスタンスを使用している場合は、Sdk クラスを使用してクライアントを作成することを強くお勧めします。Sdk クラスでは、各 SDK クライアントに対して同じ HTTP クライアントが自動的に使用されるため、異なるサービス用の SDK クライアントでノンブロッキング HTTP リクエストを実行できます。SDK クライアントで同じ HTTP クライアントを使用していない場合は、SDK が送信する HTTP リクエストによってサービス間でのプロミスオーケストレーションがブロックされます。

サービスオペレーションの実行

サービスオペレーションは、クライアントオブジェクトにある同じ名前のメソッドを呼び出すことによって実行できます。たとえば、Amazon S3 の PutObject オペレーションを実行するには、Aws\S3\S3Client::putObject() メソッドを呼び出します。

インポート 

require 'vendor/autoload.php';

use Aws\S3\S3Client;

サンプルコード 

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2'
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

// Send a PutObject request and get the result object.
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key',
    'Body' => 'this is the body!'
]);

// Download the contents of the object.
$result = $s3Client->getObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key'
]);

// Print the body of the result by indexing into the result object.
echo $result['Body'];

クライアントで使用可能なオペレーションおよび入力と出力の構造体は、サービス記述ファイルに基づいて実行時に定義されます。クライアントの作成時に、バージョン (例: "2006-03-01"、"latest") を指定する必要があります。SDK は、提供されたバージョンに基づいて、対応する設定ファイルを見つけます。

putObject() などのオペレーションメソッドはすべて、オペレーションのパラメーターを表す連想配列である単一の引数を受け入れます。この配列の構造体 (および結果オブジェクトの構造体) は、SDK の API ドキュメント (たとえば、putObject オペレーションの API ドキュメントを参照) で各オペレーションに対して定義されています。

HTTP ハンドラーオプション

特別な @http パラメーターを使用することによって、基になるハンドラーでリクエストがどのように実行されるかを調整することもできます。@http パラメータに含めることができるオプションは、「http」クライアントオプションを使用してそのクライアントをインスタンス化するときに設定できるオプションと同じです。

// Send the request through a proxy
$result = $s3Client->putObject([
    'Bucket' => 'amzn-s3-demo-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

非同期リクエスト

SDK の非同期機能を使用して、複数のコマンドを同時に送信できます。オペレーション名の後に Async を付けることによって、リクエストを非同期的に送信できます。そうすると、そのリクエストが開始されて promise が返されます。その promise には、成功すると結果オブジェクトが満たされ、失敗すると例外で拒否されます。これにより、複数の promise を作成して、基になる HTTP ハンドラーがリクエストを転送するときに複数の HTTP リクエストを同時に送信できるようになります。

インポート 

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

サンプルコード 

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();
//Listing all S3 Bucket
$CompleteSynchronously = $s3Client->listBucketsAsync();
// Block until the result is ready.
$CompleteSynchronously = $CompleteSynchronously->wait();

promise の wait メソッドを使用すると、promise が同期的に完了するように強制できます。promise が同期的に完了するように強制すると、デフォルトでは、その promise の状態が「ラップ解除」されます。つまり、promise の結果が返されるか、または検出された例外がスローされます。promise の wait() を呼び出した場合、そのプロセスは HTTP リクエストが完了するまでブロックされ、結果が入力されるかまたは例外がスローされます。

イベントループライブラリで SDK を使用する場合は、結果はブロックしないでください。代わりに、オペレーションが完了したときに、結果の then() メソッドを使用して、解決または拒否された promise にアクセスします。

インポート 

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

サンプルコード 

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

$promise = $s3Client->listBucketsAsync();
$promise
    ->then(function ($result) {
        echo 'Got a result: ' . var_export($result, true);
    })
    ->otherwise(function ($reason) {
        echo 'Encountered an error: ' . $reason->getMessage();
    });

結果オブジェクトの使用

オペレーションの実行が正常に終了すると、Aws\Result オブジェクトが返されます。SDK では、サービスの RAW XML データまたは RAW JSON データを返すのではなく、レスポンスデータが連想配列の構造体に配置されます。特定のサービスおよび基になるレスポンス構造体に関する知識に基づいて、データの一部の側面が正規化されます。

PHP 連想配列などの AWSResult オブジェクトからデータにアクセスできます。

インポート 

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

サンプルコード 

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2',
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3 = $sdk->createS3();
$result = $s3->listBuckets();
foreach ($result['Buckets'] as $bucket) {
    echo $bucket['Name'] . "\n";
}

// Convert the result object to a PHP array
$array = $result->toArray();

結果オブジェクトの内容は、実行されたオペレーションやサービスのバージョンによって異なります。各 API オペレーションの結果の構造体は、各オペレーションの API ドキュメントに記載されています。

SDK には、JSON データや PHP 配列の検索および操作に使用される DSL である JMESPath が組み込まれています。結果オブジェクトには、より詳細な宣言によって結果からデータを抽出できる search() メソッドが含まれています。

サンプルコード 

$s3 = $sdk->createS3();
$result = $s3->listBuckets();

$names = $result->search('Buckets[].Name');

エラー処理

同期エラー処理

オペレーションの実行中にエラーが発生すると、例外がスローされます。そのため、コード内でエラーを処理する必要がある場合は、オペレーションを try/catch ブロック内に配置します。SDK では、エラーが発生するとサービス固有の例外がスローされます。

次の例では Aws\S3\S3Client を使用しています。エラーがある場合にスローされる例外の型は Aws\S3\Exception\S3Exception です。SDK によってスローされるサービス固有のすべての例外は Aws\Exception\AwsException クラスから拡張されます。このクラスには、リクエスト ID、エラーコード、エラータイプなどの、失敗に関する有益な情報が含まれています。これをサポートする一部のサービスでは、レスポンスデータが連想配列構造 (Aws\Result オブジェクトに類似) に強制変換されることに注意してください。この構造は、通常の PHP 連想配列のようにアクセスできます。この toArray() メソッドは、そのようなデータを返します (存在する場合)。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

try {
    $s3Client->createBucket(['Bucket' => 'my-bucket']);
} catch (S3Exception $e) {
    // Catch an S3 specific exception.
    echo $e->getMessage();
} catch (AwsException $e) {
    // This catches the more generic AwsException. You can grab information
    // from the exception using methods of the exception object.
    echo $e->getAwsRequestId() . "\n";
    echo $e->getAwsErrorType() . "\n";
    echo $e->getAwsErrorCode() . "\n";

    // This dumps any modeled response data, if supported by the service
    // Specific members can be accessed directly (e.g. $e['MemberName'])
    var_dump($e->toArray());
}

非同期エラー処理

非同期リクエストを送信した場合には例外はスローされません。代わりに、返された promise の then() または otherwise() メソッドを使用して、結果またはエラーを受け取る必要があります。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

//Asynchronous Error Handling
$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);
$promise->otherwise(function ($reason) {
    var_dump($reason);
});

// This does the same thing as the "otherwise" function.
$promise->then(null, function ($reason) {
    var_dump($reason);
});

promise をラップ解除して、例外がスローされるようにできます。

インポート 

require 'vendor/autoload.php';

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

サンプルコード 

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);

//throw exception
try {
    $result = $promise->wait();
} catch (S3Exception $e) {
    echo $e->getMessage();
}