PHP から Queue Storage を使用する方法

[アーティクル]
01/11/2018

ヒント

Microsoft Azure ストレージエクスプローラーを試す

Microsoft Azure ストレージエクスプローラーは、Windows、macOS、Linux で Azure Storage のデータを視覚的に操作できる Microsoft 製の無料のスタンドアロンアプリです。

このガイドでは、Azure Queue Storage サービスを使用して、一般的なシナリオを実行する方法について説明します。サンプルは、PHP 用の Azure Storage クライアントライブラリのクラスを使用して記述されます。キューメッセージの挿入、ピーク、取得、削除のシナリオ、キューの作成と削除のシナリオについて説明します。

Queue storage とは

Azure キューストレージは、HTTP または HTTPS を使用した認証された呼び出しを介して世界中のどこからでもアクセスできる大量のメッセージを格納するためのサービスです。キューの 1 つのメッセージの最大サイズは 64 KB で、1 つのキューには、ストレージアカウントの合計容量の上限に達するまで、数百万のメッセージを格納できます。 Queue storage は、多くの場合、非同期的な処理用に作業のバックログを作成するために使用されます。

Queue サービスの概念

Azure Queue サービスには、次のコンポーネントが含まれます。

Azure Queue サービスコンポーネント

ストレージアカウント: Azure のストレージにアクセスする場合には必ず、ストレージアカウントを使用します。ストレージアカウントの詳細については、「ストレージアカウントの概要」を参照してください。
キュー: キューは、メッセージのセットを格納します。すべてのメッセージはキューに格納されている必要があります。キュー名は小文字で入力する必要があります。キューの名前付け規則については、「 Naming Queues and Metadata (キューとメタデータの名前付け規則)」を参照してください。
メッセージ: 形式を問わず、メッセージのサイズは最大で 64 KB です。メッセージをキューで保持できる最長時間は 7 日間です。バージョン 2017-07-29 以降では、最大有効期間を任意の正の数にすることができます。また、-1 は、メッセージが期限切れにならないことを示します。このパラメーターを省略すると、既定の有効期間は 7 日になります。
URL 形式: キューは次の URL 形式を使って処理できます: http://<storage account>.queue.core.windows.net/<queue>

次の URL を使用すると、図のいずれかのキューをアドレス指定できます。

http://myaccount.queue.core.windows.net/incoming-orders

Azure のストレージアカウントの作成

最初の Azure ストレージアカウントを作成する最も簡単な方法は、Azure Portal を利用することです。詳細については、「ストレージアカウントの作成」を参照してください。

Azure Storage アカウントは、Azure PowerShell、Azure CLI、または .NET 用 Azure ストレージリソースプロバイダーを使用して作成することもできます。

現時点で Azure にストレージアカウントを作成しない場合は、Azure ストレージエミュレーターを使って、ローカル環境でコードの実行とテストを行うこともできます。詳細については、ローカルでの Azure Storage の開発に Azurite エミュレーターを使用する方法に関するページを参照してください。

PHP アプリケーションの作成

Azure Queue Storage にアクセスする PHP アプリケーションを作成するための要件は、コード内から PHP 用の Azure Storage クライアントライブラリのクラスを参照することのみです。アプリケーションの作成には、メモ帳などの任意の開発ツールを使用できます。

このガイドで使用する Queue Storage サービス機能は、PHP アプリケーション内でローカルで呼び出すことも、Azure の Web アプリケーション内で実行されるコードで呼び出すこともできます。

Azure クライアントライブラリの入手

Composer 経由でインストールする

プロジェクトのルートに composer.json という名前のファイルを作成し、次のコードをそれに追加します。
```
{
  "require": {
    "microsoft/azure-storage-queue": "*"
  }
}
```
プロジェクトのルートに composer.phar をダウンロードします。
コマンドプロンプトを開き、次のコマンドをプロジェクトのルートで実行します。
```
php composer.phar install
```

または、GitHub で Azure Storage PHP クライアントライブラリに移動して、ソースコードを複製します。

Queue ストレージにアクセスするようにアプリケーションを構成する

Azure Queue Storage で API を使用するには、次のことが必要になります。

require_once ステートメントを使用してオートローダーファイルを参照する。
使用する可能性のあるクラスを参照する

次の例では、オートローダーファイルをインクルードし、QueueRestProxy クラスを参照する方法を示しています。

require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Queue\QueueRestProxy;

次の例では、常に require_once ステートメントが表示されますが、参照されるのは、例を実行するのに必要なクラスのみとなります。

Azure Storage の接続文字列の設定

Azure Queue Storage クライアントをインスタンス化するには、まず有効な接続文字列が必要です。 Queue Storage の接続文字列の形式は次のとおりです。

ライブサービスにアクセスする場合:

DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]

エミュレーターストレージにアクセスする場合:

UseDevelopmentStorage=true

Azure Queue Storage クライアントを作成するには、QueueRestProxy クラスを使用する必要があります。次の手法のうちどちらかを使用できます。

接続文字列を直接渡す
Web アプリで環境変数を使用して、接続文字列を格納する。接続文字列の構成については、Azure Web アプリ構成の設定に関するドキュメントを参照してください。

ここで概説している例では、接続文字列が直接渡されます。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";
$queueClient = QueueRestProxy::createQueueService($connectionString);

キューを作成する

QueueRestProxy オブジェクトを使用すると、CreateQueue メソッドを使用してキューを作成できます。キューの作成時にキューのオプションを設定できますが、この設定は必須ではありません次の例では、キューのメタデータを設定する方法を示しています。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\CreateQueueOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// OPTIONAL: Set queue metadata.
$createQueueOptions = new CreateQueueOptions();
$createQueueOptions->addMetaData("key1", "value1");
$createQueueOptions->addMetaData("key2", "value2");

try    {
    // Create queue.
    $queueClient->createQueue("myqueue", $createQueueOptions);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Note

メタデータキーでは大文字と小文字は区別されません。すべてのキーはサービスから小文字で返されます。

メッセージをキューに追加する

メッセージをキューに追加するには、QueueRestProxy->createMessage を使用します。このメソッドにはキュー名、メッセージテキスト、メッセージオプション (省略可能) を渡します。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\CreateMessageOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Create message.
    $queueClient->createMessage("myqueue", "Hello, World");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

次のメッセージをピークする

QueueRestProxy->peekMessages を呼び出すと、キューの先頭にある 1 つまたは複数のメッセージをキューから削除せずにクイック表示することができます。既定では、peekMessage メソッドからは 1 つのメッセージが返されます。しかし、この数は PeekMessagesOptions->setNumberOfMessages メソッドを使用して変更できます。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\PeekMessagesOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// OPTIONAL: Set peek message options.
$message_options = new PeekMessagesOptions();
$message_options->setNumberOfMessages(1); // Default value is 1.

try    {
    $peekMessagesResult = $queueClient->peekMessages("myqueue", $message_options);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$messages = $peekMessagesResult->getQueueMessages();

// View messages.
$messageCount = count($messages);
if($messageCount <= 0){
    echo "There are no messages.<br />";
}
else{
    foreach($messages as $message)    {
        echo "Peeked message:<br />";
        echo "Message Id: ".$message->getMessageId()."<br />";
        echo "Date: ".date_format($message->getInsertionDate(), 'Y-m-d')."<br />";
        echo "Message text: ".$message->getMessageText()."<br /><br />";
    }
}

次のメッセージをデキューする

コードでは、2 つの手順でキューからメッセージを削除します。まず、QueueRestProxy->listMessages を呼び出します。これにより、このメッセージは、このキューから読み取る他のコードからは参照できなくなります。既定では、このメッセージを参照できない状態は 30 秒間続きます。 (メッセージがこの時間内に削除されない場合、このキューで再び参照できるようになります)。キューからのメッセージの削除を完了するには、QueueRestProxy->deleteMessage を呼び出す必要があります。 2 段階の手順でメッセージを削除するこの方法では、ハードウェアまたはソフトウェアの問題が原因でコードによるメッセージの処理が失敗した場合に、コードの別のインスタンスで同じメッセージを取得し、もう一度処理することができます。ご自分のコードで、メッセージが処理された直後に deleteMessage を呼び出します。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// Get message.
$listMessagesResult = $queueClient->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

/* ---------------------
    Process message.
   --------------------- */

// Get message ID and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try    {
    // Delete message.
    $queueClient->deleteMessage("myqueue", $messageId, $popReceipt);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

キューに配置されたメッセージの内容を変更する

キュー内のメッセージの内容をインプレースで変更するには、QueueRestProxy->updateMessage を呼び出します。メッセージが作業タスクを表している場合は、この機能を使用して、作業タスクの状態を更新できます。次のコードでは、キューメッセージを新しい内容に更新し、表示タイムアウトを設定して、60 秒延長します。これにより、メッセージに関連付けられている作業の状態が保存され、クライアントにメッセージの操作を続行する時間が 1 分与えられます。この方法を使用すると、キューメッセージに対する複数の手順から成るワークフローを追跡でき、ハードウェアまたはソフトウェアの問題が原因で処理手順が失敗した場合に最初からやり直す必要がなくなります。通常は、さらに再試行回数を保持し、メッセージの再試行回数が n 回を超えた場合はメッセージを削除するようにします。こうすることで、処理するたびにアプリケーションエラーをトリガーするメッセージから保護されます。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Get message.
$listMessagesResult = $queueClient->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

// Define new message properties.
$new_message_text = "New message text.";
$new_visibility_timeout = 5; // Measured in seconds.

// Get message ID and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try    {
    // Update message.
    $queueClient->updateMessage("myqueue",
                                $messageId,
                                $popReceipt,
                                $new_message_text,
                                $new_visibility_timeout);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

メッセージのデキュー用の追加オプション

キューからのメッセージの取得をカスタマイズする方法は 2 つあります。 1 つ目の方法では、(最大 32 個の) メッセージのバッチを取得できます。 2 つ目の方法では、コードで各メッセージを完全に処理できるように、表示タイムアウトの設定を長くまたは短くすることができます。次のコード例では、getMessages メソッドを使用して、1 回の呼び出しで 16 個のメッセージを取得します。その後、for ループを使用して、各メッセージを処理します。また、各メッセージの非表示タイムアウトを 5 分に設定します。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\ListMessagesOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// Set list message options.
$message_options = new ListMessagesOptions();
$message_options->setVisibilityTimeoutInSeconds(300);
$message_options->setNumberOfMessages(16);

// Get messages.
try{
    $listMessagesResult = $queueClient->listMessages("myqueue",
                                                     $message_options);
    $messages = $listMessagesResult->getQueueMessages();

    foreach($messages as $message){

        /* ---------------------
            Process message.
        --------------------- */

        // Get message Id and pop receipt.
        $messageId = $message->getMessageId();
        $popReceipt = $message->getPopReceipt();

        // Delete message.
        $queueClient->deleteMessage("myqueue", $messageId, $popReceipt);
    }
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

キューの長さを取得する

キュー内のメッセージの概数を取得できます。 QueueRestProxy->getQueueMetadata メソッドを使用して、キューに関するメタデータを取得します。返されたオブジェクトに対して getApproximateMessageCount メソッドを呼び出すと、キュー内のメッセージの数を取得できます。要求に対して Queue Storage からの応答があった後にメッセージが追加または削除される可能性があるため、これらの値は概数にすぎません。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Get queue metadata.
    $queue_metadata = $queueClient->getQueueMetadata("myqueue");
    $approx_msg_count = $queue_metadata->getApproximateMessageCount();
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

echo $approx_msg_count;

キューを削除する

キューとキュー内のすべてのメッセージとを削除するには、QueueRestProxy->deleteQueue メソッドを呼び出します。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Delete queue.
    $queueClient->deleteQueue("myqueue");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

次のステップ

これで、Azure Queue Storage の基本を学習できました。さらに複雑なストレージタスクについては、次のリンク先を参照してください。

Azure Storage PHP クライアントライブラリの API リファレンスを参照してください
詳細な Queue の例を参照してください。

詳細については、PHP デベロッパーセンターを参照してください。

次の方法で共有

PHP から Queue Storage を使用する方法

Queue storage とは

Queue サービスの概念

Azure のストレージアカウントの作成

PHP アプリケーションの作成

Azure クライアントライブラリの入手

Composer 経由でインストールする

Queue ストレージにアクセスするようにアプリケーションを構成する

Azure Storage の接続文字列の設定

キューを作成する

メッセージをキューに追加する

次のメッセージをピークする

次のメッセージをデキューする

キューに配置されたメッセージの内容を変更する

メッセージのデキュー用の追加オプション

キューの長さを取得する

キューを削除する

次のステップ

その他のリソース

次の方法で共有

PHP から Queue Storage を使用する方法

Queue storage とは

Queue サービスの概念

Azure のストレージ アカウントの作成

PHP アプリケーションの作成

Azure クライアント ライブラリの入手

Composer 経由でインストールする

Queue ストレージにアクセスするようにアプリケーションを構成する

Azure Storage の接続文字列の設定

キューを作成する

メッセージをキューに追加する

次のメッセージをピークする

次のメッセージをデキューする

キューに配置されたメッセージの内容を変更する

メッセージのデキュー用の追加オプション

キューの長さを取得する

キューを削除する

次のステップ

その他のリソース

Azure のストレージアカウントの作成

Azure クライアントライブラリの入手