AWS SDK for PHP バージョン 3 でのウェーター - AWS SDK for PHP
ウェーターの設定非同期の待機

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

AWS SDK for PHP バージョン 3 でのウェーター

ウェーターを使用すると、リソースをポーリングしてリソースが特定の状態になるまで待機するための抽象化された方法を提供することによって、結果整合性のあるシステムでの操作が容易になります。クライアントでサポートされているウェーターの一覧は、サービスクライアントの単一のバージョンの API ドキュメントに記載されています。そこに移動するには、API ドキュメントのクライアントのページに移動し、特定のバージョン番号 (日付で表される) に移動し、[Waiters] (ウェーター) セクションまでスクロールします。このリンクをクリックすると、S3 のウェーターセクションに移動します。

次の例では、Amazon S3 クライアントを使用してバケットを作成した後に、ウェーターを使用して、そのバケットが利用可能になるまで待機しています。

// Create a bucket
$s3Client->createBucket(['Bucket' => 'my-bucket']);

// Wait until the created bucket is available
$s3Client->waitUntil('BucketExists', ['Bucket' => 'my-bucket']);

バケットに対するウェーターのポーリング回数が多すぎる場合は、\RuntimeException 例外がスローされます。

ウェーターの設定

ウェーターは、設定オプションの連想配列によって駆動されます。特定のウェーターで使用されるすべてのオプションにはデフォルト値がありますが、それをオーバーライドして異なる待機方法を指定できます。

ウェーターの設定オプションは、@waiter オプションの連想配列をクライアントの $args および waitUntil() の getWaiter() 引数に渡すことによって変更できます。

// Providing custom waiter configuration options to a waiter
$s3Client->waitUntil('BucketExists', [
    'Bucket'  => 'my-bucket',
    '@waiter' => [
        'delay'       => 3,
        'maxAttempts' => 10
    ]
]);
delay (int)

ポーリング試行間隔の秒数。各ウェーターにはデフォルトの delay 設定値がありますが、特定のユースケースに合わせてその設定を変更できます。

maxAttempts (int)

発行するポーリング試行の最大回数。この回数を超えるとウェーターは失敗します。このオプションにより、リソースを無期限に待機しなくなります。各ウェーターにはデフォルトの maxAttempts 設定値がありますが、特定のユースケースに合わせてその設定を変更できます。

initDelay (int)

最初のポーリング試行までの待機時間 (秒)。これは、目的の状態になるまでにしばらく時間がかかることがわかっているリソースを待機する場合に便利です。

before (callable)

各ポーリング試行の前に呼び出す、PHP で呼び出し可能な関数。この呼び出し可能な関数の呼び出しでは、実行されようとしている Aws\CommandInterface コマンドと実行済みの試行回数が渡されます。before 呼び出し可能関数を使用すると、実行する前にコマンドを変更したり、進行状況を提供したりできます。

use Aws\CommandInterface;

$s3Client->waitUntil('BucketExists', [
    'Bucket'  => 'my-bucket',
    '@waiter' => [
        'before' => function (CommandInterface $command, $attempts) {
            printf(
                "About to send %s. Attempt %d\n",
                $command->getName(),
                $attempts
            );
        }
    ]
]);

非同期の待機

同期的に待機するだけでなく、他のリクエストの送信中や複数のリソースの同時待機中に、ウェーターを呼び出して非同期で待機することもできます。

クライアントの getWaiter($name, array $args = []) メソッドを使用してクライアントからウェーターを取得することによって、ウェーターの promise にアクセスできます。ウェーターを開始するには、ウェーターの promise() メソッドを使用します。ウェーターの promise には、ウェーターで実行された最後の Aws\CommandInterface が満たされ、エラー発生時には RuntimeException で拒否されます。

use Aws\CommandInterface;

$waiterName = 'BucketExists';
$waiterOptions = ['Bucket' => 'my-bucket'];

// Create a waiter promise
$waiter = $s3Client->getWaiter($waiterName, $waiterOptions);

// Initiate the waiter and retrieve a promise
$promise = $waiter->promise();

// Call methods when the promise is resolved.
$promise
    ->then(function () {
        echo "Waiter completed\n";
    })
    ->otherwise(function (\Exception $e) {
        echo "Waiter failed: " . $e . "\n";
    });

// Block until the waiter completes or fails. Note that this might throw
// a \RuntimeException if the waiter fails.
$promise->wait();

promise ベースのウェーター API を公開すると、ある程度強力でオーバーヘッドが比較的小さいユースケースに効果があります。たとえば、複数のリソースを待機する場合に、最初に解決されたウェーターで何か行うにはどうしたらよいでしょうか。

use Aws\CommandInterface;

// Create an array of waiter promises
$promises = [
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'a'])->promise(),
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'b'])->promise(),
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'c'])->promise()
];

// Initiate a race between the waiters, fulfilling the promise with the
// first waiter to complete (or the first bucket to become available)
$any = Promise\any($promises)
    ->then(function (CommandInterface $command) {
        // This is invoked with the command that succeeded in polling the
        // resource. Here we can know which bucket won the race.
        echo "The {$command['Bucket']} waiter completed first!\n";
    });

// Force the promise to complete
$any->wait();