PHP で Service Bus キューを使用する方法How to use Service Bus queues with PHP

このチュートリアルでは、PHP アプリケーションを作成して、Service Bus キューとの間でメッセージを送受信する方法を学習します。In this tutorial, you learn how to create PHP applications to send messages to and receive messages from a Service Bus queue.

前提条件Prerequisites

  1. Azure サブスクリプション。An Azure subscription. このチュートリアルを完了するには、Azure アカウントが必要です。To complete this tutorial, you need an Azure account. MSDN のサブスクライバー特典を有効にするか、無料アカウントにサインアップしてください。You can activate your MSDN subscriber benefits or sign up for a free account.
  2. 使用するキューがない場合は、「Azure portal を使用して Service Bus キューを作成する」の記事にある手順に従って、キューを作成します。If you don't have a queue to work with, follow steps in the Use Azure portal to create a Service Bus queue article to create a queue.
    1. Service Bus キュー概要をお読みください。Read the quick overview of Service Bus queues.

    2. Service Bus 名前空間を作成します。Create a Service Bus namespace.

    3. 接続文字列を取得します。Get the connection string.

      注意

      このチュートリアルでは、PHP を使用して Service Bus 名前空間でキューを作成します。You will create a queue in the Service Bus namespace by using PHP in this tutorial.

  3. Azure SDK for PHPAzure SDK for PHP

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

Microsoft Azure Blob service にアクセスする PHP アプリケーションを作成するための要件は、コード内から Microsoft Azure SDK for PHP のクラスを参照することのみです。The only requirement for creating a PHP application that accesses the Azure Blob service is the referencing of classes in the Azure SDK for PHP from within your code. アプリケーションの作成には任意の開発ツールまたはメモ帳を使用できます。You can use any development tools to create your application, or Notepad.

注意

PHP のインストールでは、OpenSSL 拡張機能をインストールして有効にしておく必要もあります。Your PHP installation must also have the OpenSSL extension installed and enabled.

このガイドで使用するサービス機能は、PHP アプリケーション内からローカルで呼び出すことも、Azure の Web ロール、worker ロール、Web サイト上で実行されるコード内で呼び出すこともできます。In this guide, you will use service features, which can be called from within a PHP application locally, or in code running within an Azure web role, worker role, or website.

Azure クライアント ライブラリの入手Get the Azure client libraries

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

  1. プロジェクトのルートに composer.json という名前のファイルを作成して、次のコードを追加します。Create a file named composer.json in the root of your project and add the following code to it:

    {
      "require": {
        "microsoft/azure-storage": "*"
      }
    }
    
  2. composer.phar をプロジェクトのルートにダウンロードします。Download composer.phar in your project root.

  3. コマンド プロンプトを開き、次のコマンドをプロジェクトのルートで実行します。Open a command prompt and execute the following command in your project root

    php composer.phar install
    

または、GitHub で Azure Storage PHP Client Library に移動し、ソース コードを複製します。Alternatively go to the Azure Storage PHP Client Library on GitHub to clone the source code.

Service Bus を使用するようにアプリケーションを構成するConfigure your application to use Service Bus

Service Bus キュー API を使用するには、次の操作を行います。To use the Service Bus queue APIs, do the following:

  1. require_once ステートメントを使用してオートローダー ファイルを参照するReference the autoloader file using the require_once statement.
  2. 使用する可能性のあるクラスを参照するReference any classes you might use.

次の例では、オートローダー ファイルをインクルードし、ServicesBuilder クラスを参照する方法を示しています。The following example shows how to include the autoloader file and reference the ServicesBuilder class.

注意

この例 (およびこの記事のその他の例) では、Composer を使用して Azure 向け PHP クライアント ライブラリがインストールされていることを前提としています。This example (and other examples in this article) assumes you have installed the PHP Client Libraries for Azure via Composer. ライブラリを手動でまたは PEAR パッケージとしてインストールした場合は、WindowsAzure.php オートローダー ファイルを参照する必要があります。If you installed the libraries manually or as a PEAR package, you must reference the WindowsAzure.php autoloader file.

require_once 'vendor/autoload.php';
use WindowsAzure\Common\ServicesBuilder;

下のすべてのサンプルに require_once ステートメントが入っていますが、サンプルの実行に必要なクラスのみが参照されます。In the examples below, the require_once statement will always be shown, but only the classes necessary for the example to execute are referenced.

Service Bus 接続の設定Set up a Service Bus connection

Service Bus クライアントをインスタンス化するには、まず次の形式の有効な接続文字列が必要です。To instantiate a Service Bus client, you must first have a valid connection string in this format:

Endpoint=[yourEndpoint];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[Primary Key]

ここで、Endpoint の一般的な形式は [yourNamespace].servicebus.windows.net です。Where Endpoint is typically of the format [yourNamespace].servicebus.windows.net.

いずれかの Azure サービス クライアントを作成するには、ServicesBuilder クラスを使用する必要があります。To create any Azure service client, you must use the ServicesBuilder class. 次のようにすることができます。You can:

  • 接続文字列を直接渡すPass the connection string directly to it.
  • CloudConfigurationManager (CCM) を使用して複数の外部ソースに対して接続文字列を確認するUse the CloudConfigurationManager (CCM) to check multiple external sources for the connection string:
    • 既定では 1 つの外部ソース (環境変数) のみがサポートされています。By default it comes with support for one external source - environmental variables
    • ConnectionStringSource クラスを拡張して新しいソースを追加できます。You can add new sources by extending the ConnectionStringSource class

ここで概説している例では、接続文字列が直接渡されます。For the examples outlined here, the connection string is passed directly.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;

$connectionString = "Endpoint=[yourEndpoint];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[Primary Key]";

$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

キューを作成するCreate a queue

ServiceBusRestProxy クラスを使用して Service Bus キューに対する管理操作を実行できます。You can perform management operations for Service Bus queues via the ServiceBusRestProxy class. ServicesBuilder::createServiceBusService ファクトリ メソッドを介して、ServiceBusRestProxy オブジェクトがトークン アクセス許可をカプセル化してそれを管理する適切な接続文字列とともに構築されます。A ServiceBusRestProxy object is constructed via the ServicesBuilder::createServiceBusService factory method with an appropriate connection string that encapsulates the token permissions to manage it.

次の例では、ServiceBusRestProxy をインスタンス化し、ServiceBusRestProxy->createQueue を呼び出して、MySBNamespace サービス名前空間内で myqueue という名前のキューを作成する方法を示しています。The following example shows how to instantiate a ServiceBusRestProxy and call ServiceBusRestProxy->createQueue to create a queue named myqueue within a MySBNamespace service namespace:

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\QueueInfo;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    $queueInfo = new QueueInfo("myqueue");

    // Create queue.
    $serviceBusRestProxy->createQueue($queueInfo);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

注意

ServiceBusRestProxy オブジェクトの listQueues メソッドを使用すると、指定した名前のキューが名前空間に既に存在するかどうかを確認できます。You can use the listQueues method on ServiceBusRestProxy objects to check if a queue with a specified name already exists within a namespace.

メッセージをキューに送信するSend messages to a queue

メッセージを Service Bus キューに送信するには、アプリケーションで ServiceBusRestProxy->sendQueueMessage メソッドを呼び出します。To send a message to a Service Bus queue, your application calls the ServiceBusRestProxy->sendQueueMessage method. 次のコードでは、上のコードで MySBNamespace サービス名前空間内で作成した myqueue キューにメッセージを送信する方法を示しています。The following code shows how to send a message to the myqueue queue previously created within the MySBNamespace service namespace.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\BrokeredMessage;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Create message.
    $message = new BrokeredMessage();
    $message->setBody("my message");

    // Send message.
    $serviceBusRestProxy->sendQueueMessage("myqueue", $message);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Service Bus キューに送信されたメッセージ (および Service Bus キューから受信したメッセージ) は、BrokeredMessage クラスのインスタンスになります。Messages sent to (and received from) Service Bus queues are instances of the BrokeredMessage class. BrokeredMessage オブジェクトには、アプリケーションに特有のカスタム プロパティの保持に使用する標準的なプロパティやメソッド、および任意のアプリケーション データの本体が含まれています。BrokeredMessage objects have a set of standard methods and properties that are used to hold custom application-specific properties, and a body of arbitrary application data.

Service Bus キューでサポートされているメッセージの最大サイズは、Standard レベルでは 256 KB、Premium レベルでは 1 MB です。Service Bus queues support a maximum message size of 256 KB in the Standard tier and 1 MB in the Premium tier. 標準とカスタムのアプリケーション プロパティが含まれるヘッダーの最大サイズは 64 KB です。The header, which includes the standard and custom application properties, can have a maximum size of 64 KB. キューで保持されるメッセージ数には上限がありませんが、キュー 1 つあたりが保持できるメッセージの合計サイズには上限があります。There is no limit on the number of messages held in a queue but there is a cap on the total size of the messages held by a queue. このキュー サイズの上限は 5 GB です。This upper limit on queue size is 5 GB.

キューからメッセージを受信するReceive messages from a queue

キューからメッセージを受信する最適な方法は、ServiceBusRestProxy->receiveQueueMessage メソッドを使用する方法です。The best way to receive messages from a queue is to use a ServiceBusRestProxy->receiveQueueMessage method. メッセージは 2 つの異なるモードで受信できます。ReceiveAndDeletePeekLock です。Messages can be received in two different modes: ReceiveAndDelete and PeekLock. PeekLock が既定値です。PeekLock is the default.

ReceiveAndDelete モードを使用する場合、受信が 1 回ずつの動作になります。つまり、Service Bus はキュー内のメッセージに対する読み取り要求を受け取ると、メッセージを読み取り中としてマークし、アプリケーションに返します。When using ReceiveAndDelete mode, receive is a single-shot operation; that is, when Service Bus receives a read request for a message in a queue, it marks the message as being consumed and returns it to the application. ReceiveAndDelete モードは最もシンプルなモデルであり、障害発生時にアプリケーション側でメッセージを処理しないことを許容できるシナリオに最適です。ReceiveAndDelete mode is the simplest model and works best for scenarios in which an application can tolerate not processing a message in the event of a failure. このことを理解するために、コンシューマーが受信要求を発行した後で、メッセージを処理する前にクラッシュしたというシナリオを考えてみましょう。To understand this, consider a scenario in which the consumer issues the receive request and then crashes before processing it. Service Bus はメッセージを読み取り済みとしてマークするため、アプリケーションが再起動してメッセージの読み取りを再開すると、クラッシュ前に読み取られていたメッセージは見落とされることになります。Because Service Bus will have marked the message as being consumed, then when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.

既定の PeekLock モードでは、メッセージの受信処理が 2 段階の動作になり、メッセージが失われることが許容できないアプリケーションに対応することができます。In the default PeekLock mode, receiving a message becomes a two stage operation, which makes it possible to support applications that cannot tolerate missing messages. Service Bus は要求を受け取ると、次に読み取られるメッセージを検索して、他のコンシューマーが受信できないようロックしてから、アプリケーションにメッセージを返します。When Service Bus receives a request, it finds the next message to be consumed, locks it to prevent other consumers from receiving it, and then returns it to the application. アプリケーションがメッセージの処理を終えた後 (または後で処理するために確実に保存した後)、受信したメッセージを ServiceBusRestProxy->deleteMessage に渡すことで受信処理の第 2 段階を完了します。After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by passing the received message to ServiceBusRestProxy->deleteMessage. Service Bus が deleteMessage の呼び出しを確認すると、メッセージが読み取り中としてマークされ、キューから削除されます。When Service Bus sees the deleteMessage call, it will mark the message as being consumed and remove it from the queue.

次の例は、PeekLock モード (既定のモード) を使用したメッセージの受信および処理の方法を示しています。The following example shows how to receive and process a message using PeekLock mode (the default mode).

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\ReceiveMessageOptions;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Set the receive mode to PeekLock (default is ReceiveAndDelete).
    $options = new ReceiveMessageOptions();
    $options->setPeekLock();

    // Receive message.
    $message = $serviceBusRestProxy->receiveQueueMessage("myqueue", $options);
    echo "Body: ".$message->getBody()."<br />";
    echo "MessageID: ".$message->getMessageId()."<br />";

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

    // Delete message. Not necessary if peek lock is not set.
    echo "Message deleted.<br />";
    $serviceBusRestProxy->deleteMessage($message);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

アプリケーションのクラッシュと読み取り不能のメッセージを処理する方法How to handle application crashes and unreadable messages

Service Bus には、アプリケーションにエラーが発生した場合や、メッセージの処理に問題がある場合に復旧を支援する機能が備わっています。Service Bus provides functionality to help you gracefully recover from errors in your application or difficulties processing a message. 受信側のアプリケーションがなんらかの理由によってメッセージを処理できない場合には、受信したメッセージについて (deleteMessage メソッドの代わりに) unlockMessage メソッドを呼び出すことができます。If a receiver application is unable to process the message for some reason, then it can call the unlockMessage method on the received message (instead of the deleteMessage method). このメソッドが呼び出されると、Service Bus によってキュー内のメッセージのロックが解除され、メッセージが再度受信できる状態に変わります。メッセージを受信するアプリケーションは、以前と同じものでも、別のものでもかまいません。This will cause Service Bus to unlock the message within the queue and make it available to be received again, either by the same consuming application or by another consuming application.

キュー内でロックされているメッセージには、タイムアウトも設定されています。アプリケーションがクラッシュした場合など、ロックがタイムアウトになる前にアプリケーションがメッセージの処理に失敗した場合は、Service Bus によってメッセージのロックが自動的に解除され、再度受信できる状態に変わります。There is also a timeout associated with a message locked within the queue, and if the application fails to process the message before the lock timeout expires (for example, if the application crashes), then Service Bus will unlock the message automatically and make it available to be received again.

メッセージが処理された後、deleteMessage 要求が発行される前にアプリケーションがクラッシュした場合は、アプリケーションが再起動する際にメッセージが再配信されます。In the event that the application crashes after processing the message but before the deleteMessage request is issued, then the message will be redelivered to the application when it restarts. 一般的に、この動作は 1 回以上の処理と呼ばれます。つまり、すべてのメッセージが 1 回以上処理されますが、特定の状況では、同じメッセージが再配信される可能性があります。This is often called At Least Once processing; that is, each message is processed at least once but in certain situations the same message may be redelivered. 重複処理が許されないシナリオの場合、重複メッセージの配信を扱うロジックをアプリケーションに追加することをお勧めします。If the scenario cannot tolerate duplicate processing, then adding additional logic to applications to handle duplicate message delivery is recommended. 通常、この問題はメッセージの getMessageId メソッドを使用して対処します。このプロパティは配信が試行された後も同じ値を保持します。This is often achieved using the getMessageId method of the message, which remains constant across delivery attempts.

注意

Service Bus リソースは、Service Bus Explorer で管理できます。You can manage Service Bus resources with Service Bus Explorer. Service Bus Explorer を使用すると、ユーザーは Service Bus 名前空間に接続し、簡単な方法でメッセージング エンティティを管理できます。The Service Bus Explorer allows users to connect to a Service Bus namespace and administer messaging entities in an easy manner. このツールには、インポート/エクスポート機能や、トピック、キュー、サブスクリプション、リレー サービス、通知ハブ、イベント ハブをテストする機能などの高度な機能が用意されています。The tool provides advanced features like import/export functionality or the ability to test topic, queues, subscriptions, relay services, notification hubs and events hubs.

次の手順Next steps

これで、Service Bus キューの基本を学習できました。詳細については、「Service Bus のキュー、トピック、サブスクリプション」をご覧ください。Now that you've learned the basics of Service Bus queues, see Queues, topics, and subscriptions for more information.

詳しくは、PHP デベロッパー センターもご覧ください。For more information, also visit the PHP Developer Center.