クイックスタート

SDKのインクルード

SDKは、 インストール方法 にかかわらず、include文 (またはrequire文) 1行で プロジェクトやスクリプトに組み込むことができます。 インストール方法に応じた、最適なコードの書き方を表に示します。 /path/to/ の部分はシステムに応じた実際のパスに置き換えてください。

インストール方法 インクルードに用いる文
Pharを使用 require '/path/to/aws.phar';
Zipを使用 require '/path/to/aws-autoloader.php';

このガイドではComposerを使ってインストールしたものとして例を示します。 それ以外の方法でインストールした場合は、適宜読み替えてください。

クライアントの生成

ウェブサービスクライアントのファクトリメソッドを使えば、必要に応じてすぐにクライアントのインスタンスを生成できます。

<?php

// Include the SDK using the Composer autoloader
require 'vendor/autoload.php';

use Aws\S3\S3Client;

// Instantiate the S3 client with your AWS credentials and desired AWS region
$client = S3Client::factory(array(
    'key'    => 'your-aws-access-key-id',
    'secret' => 'your-aws-secret-access-key',
));

注: 証明書を与えずにクライアントのインスタンスを生成しようとすると、クライアントは IAMインスタンスプロファイル証明書 の取得を試みます。 インスタンスプロファイル証明書はすべてのサービスでサポートされているわけではありません。 利用しているサービスがサポートしているテンポラリ証明書をチェックして下さい

コマンド

オペレーション名と対応するパラメータの連想配列をクライアントに渡すことでクライアントに対するサービスオペレーションを呼び出すことができます。 Amazon S3の createBucket() のようなサービスオペレーションメソッドは、 実際にはクライアント側に存在しません。 これらのメソッドはクライアントの __call() マジックメソッドを使って実装されています。 このマジックメソッドは、 Resources ディレクトリ以下のクライアントの名前空間にある、 Guzzle サービス記述 に基づいて処理を行います。 APIの資料 の他、サービス記述を直接参照しても、 どのようなオペレーションがあるか、どのようなパラメータを渡せるか、 当該オペレーションを呼び出したとき、応答モデルにどのような値が設定され、 どのような例外が発生しうるか、を調べることができます。

$bucket = 'my-bucket';

$result = $client->createBucket(array(
    'Bucket' => $bucket
));

// Wait until the bucket is created
$client->waitUntil('BucketExists', array('Bucket' => $bucket));

コマンドの実行

コマンドの実行方法は2通りあります。ひとつは __call() マジックメソッドを介して短縮構文を用いる方法 (先の例を参照)、 もうひとつはクライアントオブジェクトの getCommand() メソッドを使って拡張構文で記述する方法です。

// The shorthand syntax (via __call())
$result = $client->createBucket(array(/* ... */));

// The expanded syntax (via getCommand())
$command = $client->getCommand('CreateBucket', array(/* ... */));
$result = $command->getResult();

拡張構文の場合、 getCommand() からは Command オブジェクトが返されます。 これはニフティクラウドに対するHTTP要求および応答をカプセル化したものです。 Command オブジェクトから getResult() メソッドや execute() メソッドを呼び出して、コマンドを実行し、パース済みの結果を取得できます。 さらに、(コマンド実行後に) getRequest() メソッドや getResponse() メソッドで、 要求や応答に関する情報 (状態コード、生の応答、要求として送信されたヘッダなど) を取得できます。

Command オブジェクトのメソッドを連結して記述する方式も可能で、 要求に何らかの設定を施した上で実行したい場合に便利です。

$result = $client->getCommand('ListObjects')
    ->set('MaxKeys', 50)
    ->set('Prefix', 'foo/baz/')
    ->getResult();

複数のコマンドを並列実行することもできます。

$ops = array();
$ops[] = $client->getCommand('GetObject', array('Bucket' => 'foo', 'Key' => 'Bar'));
$ops[] = $client->getCommand('GetObject', array('Bucket' => 'foo', 'Key' => 'Baz'));
$client->execute($ops);

応答モデル

コマンドの結果は Model (Guzzle\Service\Resource\Model) オブジェクトです。 このオブジェクトは、レスポンスボディからの結果を含み、配列 (例 $result['TableName']) として利用することができます。 また、このオブジェクトは get()getPath()toArray() のようなメソッドを利用することができます。 レスポンスモデルの内容は、実行され API docs に記述されたそれぞれの操作コマンドによります。 (例 S3 GetObject operation の API docs の Returns セクションをご参照ください。

// Use an instance of S3Client to get an object
$result = $client->getObject(array(
    'Bucket' => 'my-bucket',
    'Key'    => 'test.txt'
));

// Introspect the keys
var_export($result->getKeys());
//> array( 'Body', 'ContentLength', 'DeleteMarker', 'Expiration', ... )

// Get a value
echo $result['ContentLength'];
// OR
echo $result->get('ContentLength');
//> 6

// Get a nested value
echo $result->getPath('Metadata/CustomValue');
//> Testing123

// Get an array of the data
var_export($result->toArray());
//> array ( 'Body' => 'Hello!' , 'ContentLength' => 6, ... )

モデルの操作方法については、詳しいガイド (応答モデル) を参照してください。

サービスビルダの使い方

SDKを導入すれば、個々のクライアントや Aws\Common\Aws のファクトリメソッドを使って、 クライアントを構築できるようになります。 Aws\Common\Aws クラスはサービスビルダであり、SDKに対しては「依存性の注入」コンテナとしても振る舞うので、 クライアントのインスタンスを生成する方法として推奨します。 サービスビルダを使うと、複数のサービス間で設定オプションを共有でき、 また、短いサービス名をあらかじめ適切なクライアントクラスに結びつけておくことも可能です。

サービスビルダを使って Aws\DynamoDb\DynamoDbClient を取得し、 コマンド構文により GetItem オペレーションを実行する例を示します。

適切なパラメータの配列を、 Aws\Common\Aws::factory() の第1引数または第2引数として渡すことになるので、 ビルダが生成したクライアントすべてにわたってパラメータを共有できます。 この例では、サービスビルダに対し、どのクライアントにも同じ証明書を使うよう指示しています。

<?php

require 'vendor/autoload.php';

use Aws\Common\Aws;
use Aws\DynamoDb\Exception\DynamoDbException;

// Create a service building using shared credentials for each service
$aws = Aws::factory(array(
    'key'    => 'your-aws-access-key-id',
    'secret' => 'your-aws-secret-access-key',
    'region' => 'us-west-2'
));

// Retrieve the DynamoDB client by its short name from the service builder
$client = $aws->get('dynamodb');

// Get an item from the "posts"
try {
    $result = $client->getItem(array(
        'TableName' => 'posts',
        'Key' => $client->formatAttributes(array(
            'HashKeyElement' => 'using-dynamodb-with-the-php-sdk'
        )),
        'ConsistentRead' => true
    ));

    print_r($result['Item']);
} catch (DynamoDbException $e) {
    echo 'The item could not be retrieved.';
}

適切なパラメータの配列を、 Aws\Common\Aws::factory() の第1引数または第2引数として渡すことになるので、 ビルダが生成したクライアントすべてにわたってパラメータを共有できます。 上の例では、サービスビルダに対し、どのクライアントにも同じ証明書を使うよう指示しています。

エラー処理

エラーが見つかると例外が発生します。 アプリケーションにエラー処理ロジックを実装する際は、try/catchブロックを使ってください。 サーバ側でエラーが発生すると、SDKはサービスに応じた例外を投げます。

use Aws\Common\Aws;
use Aws\S3\Exception\BucketAlreadyExistsException;

$aws = Aws::factory('/path/to/my_config.json');
$s3 = $aws->get('s3');

try {
    $s3->createBucket(array('Bucket' => 'my-bucket'));
} catch (BucketAlreadyExistsException $e) {
    echo 'That bucket already exists! ' . $e->getMessage() . "\n";
}

createBucket() メソッドに対するHTTP応答として、 BucketAlreadyExists というエラーコードの、 409 Conflict という応答が得られます。 SDKはエラーコードを検出すると、HTTP応答のエラーコードに対応する名前の例外を投げます。 各クライアントから発生しうる例外の完全なリストは、クライアントの名前空間における、 Exception/ ディレクトリを調べれば分かります。 例えば src/Aws/S3/Exception 以下には、次のようにさまざまな例外クラスがあります:

.
├── AccessDeniedException.php
├── AccountProblemException.php
├── AmbiguousGrantByEmailAddressException.php
├── BadDigestException.php
├── BucketAlreadyExistsException.php
├── BucketAlreadyOwnedByYouException.php
├── BucketNotEmptyException.php
[...]

Waiter

SDK によって提供されている高次の抽象化のひとつに、 waiter の概念があります。 Waiter によって 結果整合性 (eventually consistent) システムを簡単に利用することができます。 それは、 Waiter がリソースが特定の状態になるまでリソースをポーリングすることが容易にしてくれるためです。 クライアントの docblock を見ることで、クライアントによってサポートされている waiter のリストを知ることができます。 "waitUntil" で始まっている @method タグは waiter を使うことができます。

$client->waitUntilBucketExists(array('Bucket' => 'my-bucket'));

先のメソッド呼び出しで waiter オブジェクトをインスタンス化し、 bucket が存在するまでポーリングすることができます。

Waiter の使い方や設定方法については、詳しいガイド (Waiter) を参照してください。

イテレータ

Some AWS operations return truncated results that require subsequent requests in order to retrieve the entire result set. The subsequent requests typically require pagination tokens or markers from the previous request in order to retrieve the next set of results. Working with these tokens can be cumbersome, since you must manually keep track of them, and the API for each service you are using may differ in the names and details of the tokens.

The AWS SDK for PHP has a feature called Iterators that allow you to retrieve an entire result set without manually handling pagination tokens or markers. The Iterators in the SDK implement PHP's Iterator interface, which allows you to easily enumerate or iterate through resources from a result set with foreach.

Operations that start with List or Describe, or any other operations that are designed to return multiple records can be used with Iterators. To use an Iterator, you must call the getIterator() method of the client and provide the operation name. The following is an example of creating an Amazon S3 ListObjects Iterator, to iterate over objects in a bucket.

$iterator = $client->getIterator('ListObjects', array('Bucket' => 'my-bucket'));

foreach ($iterator as $object) {
    echo $object['Key'] . "\n";
}

イテレータのより詳細な利用方法や設定については、 Iterators の詳細なガイドを御覧ください。