Azure の Service Bus キューを Node.js および azure-sb パッケージで使用するUse Service Bus queues in Azure with Node.js and the azure-sb package

このチュートリアルでは、azure-sb パッケージを使用して、Node.js アプリケーションを作成して、Azure Service Bus キューとの間でメッセージを送受信する方法を学習します。In this tutorial, you learn how to create Node.js applications to send messages to and receive messages from an Azure Service Bus queue using the azure-sb package. サンプルは JavaScript で記述されます。このサンプルでは、azure-sb パッケージを内部で使用する Node.js Azure モジュールが使用されます。The samples are written in JavaScript and use the Node.js Azure module which internally uses the azure-sb package.

azure-sb パッケージでは Service Bus REST ランタイム API が使用されています。The azure-sb package uses Service Bus REST run-time APIs. より高速な AMQP 1.0 プロトコルが使用される新しい @azure/service-bus を使用すると、高速なエクスペリエンスが得られます。You can get a faster experience using the new @azure/service-bus which uses the faster AMQP 1.0 protocol. 新しいパッケージの詳細を知るには、Service Bus キューを Node.js と @azure/service-bus パッケージで使用する方法に関する記事を参照してください。または、azure パッケージの使用方法についてさらに読み進めてください。To learn more about the new package, see How to use Service Bus queues with Node.js and @azure/service-bus package, otherwise continue reading to see how to use the azure package.

前提条件Prerequisites

  • 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.
  • 使用するキューがない場合は、「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.

      注意

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

Node.js アプリケーションの作成Create a Node.js application

空の Node.js アプリケーションを作成します。Create a blank Node.js application. Node.js アプリケーションを作成する手順については、「Node.js アプリケーションの作成と Azure Web サイトへのデプロイ」または「Node.js クラウド サービス」 (Windows PowerShell の使用) を参照してください。For instructions on how to create a Node.js application, see Create and deploy a Node.js application to an Azure Website, or Node.js Cloud Service using Windows PowerShell.

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

Azure Service Bus を使用するには、Node.js Azure パッケージをダウンロードして使用します。To use Azure Service Bus, download and use the Node.js Azure package. このパッケージには、Service Bus REST サービスと通信するためのライブラリのセットが含まれています。This package includes a set of libraries that communicate with the Service Bus REST services.

ノード パッケージ マネージャー (NPM) を使用してパッケージを取得するUse Node Package Manager (NPM) to obtain the package

  1. Windows PowerShell for Node.js コマンド ウィンドウを使用して、サンプル アプリケーションを作成した c:\node\sbqueues\WebRole1 フォルダーに移動します。Use the Windows PowerShell for Node.js command window to navigate to the c:\node\sbqueues\WebRole1 folder in which you created your sample application.

  2. コマンド ウィンドウに「npm install azure」と入力すると、次の例のような出力が生成されます。Type npm install azure in the command window, which should result in output similar to the following example:

    azure@0.7.5 node_modules\azure
        ├── dateformat@1.0.2-1.2.3
        ├── xmlbuilder@0.4.2
        ├── node-uuid@1.2.0
        ├── mime@1.2.9
        ├── underscore@1.4.4
        ├── validator@1.1.1
        ├── tunnel@0.0.2
        ├── wns@0.5.3
        ├── xml2js@0.2.7 (sax@0.5.2)
        └── request@2.21.0 (json-stringify-safe@4.0.0, forever-agent@0.5.0, aws-sign@0.3.0, tunnel-agent@0.3.0, oauth-sign@0.3.0, qs@0.6.5, cookie-jar@0.3.0, node-uuid@1.4.0, http-signature@0.9.11, form-data@0.0.8, hawk@0.13.1)
    
  3. 手動で ls コマンドを実行して、node_modules フォルダーが作成されたことを確認することもできます。You can manually run the ls command to verify that a node_modules folder was created. そのフォルダーで azure パッケージを検索します。この中には、Service Bus キューにアクセスするために必要なライブラリが含まれています。Inside that folder, find the azure package, which contains the libraries you need to access Service Bus queues.

モジュールのインポートImport the module

メモ帳などのテキスト エディターを使用して、アプリケーションの server.js ファイルの先頭に次の内容を追加します。Using Notepad or another text editor, add the following to the top of the server.js file of the application:

var azure = require('azure');

Azure Service Bus 接続の設定Set up an Azure Service Bus connection

Azure モジュールは、Service Bus に接続するために必要な情報を得るために、環境変数 AZURE_SERVICEBUS_CONNECTION_STRING を読み取ります。The Azure module reads the environment variable AZURE_SERVICEBUS_CONNECTION_STRING to obtain information required to connect to Service Bus. この環境変数が設定されていない場合は、createServiceBusService を呼び出すときにアカウント情報を指定する必要があります。If this environment variable isn't set, you must specify the account information when calling createServiceBusService.

Azure Web サイトの Azure portal で環境変数を設定する例については、「ストレージを使用する Node.js Web アプリケーション」をご覧ください。For an example of setting the environment variables in the Azure portal for an Azure Website, see Node.js Web Application with Storage.

キューを作成するCreate a queue

Service Bus キューは、ServiceBusService オブジェクトを使用して操作できます。The ServiceBusService object enables you to work with Service Bus queues. 次のコードでは、ServiceBusService オブジェクトを作成します。The following code creates a ServiceBusService object. server.js ファイルの先頭付近の、azure モジュールをインポートするステートメントの後に、このコードを追加します。Add it near the top of the server.js file, after the statement to import the Azure module:

var serviceBusService = azure.createServiceBusService();

ServiceBusService オブジェクトの createQueueIfNotExists を呼び出すことによって、指定されたキューが返されるか (存在する場合)、指定された名前で新しいキューが作成されます。By calling createQueueIfNotExists on the ServiceBusService object, the specified queue is returned (if it exists), or a new queue with the specified name is created. 次のコードでは、createQueueIfNotExists を使用して、myqueue という名前のキューを作成、またはキューに接続します。The following code uses createQueueIfNotExists to create or connect to the queue named myqueue:

serviceBusService.createQueueIfNotExists('myqueue', function(error){
    if(!error){
        // Queue exists
    }
});

createServiceBusService メソッドは追加のオプションもサポートしています。これにより、メッセージの有効期間や最大キュー サイズなどの既定のキューの設定をオーバーライドできます。The createServiceBusService method also supports additional options, which enable you to override default queue settings such as message time to live or maximum queue size. 次の例では、最大キュー サイズを 5 GB に、有効期間を 1 分に設定します。The following example sets the maximum queue size to 5 GB, and a time to live (TTL) value of 1 minute:

var queueOptions = {
      MaxSizeInMegabytes: '5120',
      DefaultMessageTimeToLive: 'PT1M'
    };

serviceBusService.createQueueIfNotExists('myqueue', queueOptions, function(error){
    if(!error){
        // Queue exists
    }
});

フィルターFilters

オプションのフィルター操作は、ServiceBusService を使用して行われる操作に適用できます。Optional filtering operations can be applied to operations performed using ServiceBusService. フィルター操作には、ログや自動的な再試行などが含まれる場合があります。フィルターは、次のシグネチャを持つメソッドを実装するオブジェクトです。Filtering operations can include logging, automatically retrying, etc. Filters are objects that implement a method with the signature:

function handle (requestOptions, next)

要求オプションに対するプリプロセスを行った後で、このメソッドは next を呼び出して、次のシグネチャのコールバックを渡す必要があります。After doing its pre-processing on the request options, the method must call next, passing a callback with the following signature:

function (returnObject, finalCallback, next)

このコールバックで、returnObject (サーバーへの要求からの応答) の処理の後に、コールバックによって next を呼び出すか (他のフィルターの処理を続けるためにそれが存在する場合)、サービス呼び出しを終了させる finalCallback を呼び出す必要があります。In this callback, and after processing the returnObject (the response from the request to the server), the callback must either invoke next if it exists to continue processing other filters, or invoke finalCallback, which ends the service invocation.

再試行のロジックを実装する 2 つのフィルター (ExponentialRetryPolicyFilterLinearRetryPolicyFilter) が、Azure SDK for Node.js に含まれています。Two filters that implement retry logic are included with the Azure SDK for Node.js, ExponentialRetryPolicyFilter and LinearRetryPolicyFilter. 次のコードは ExponentialRetryPolicyFilter を使用する ServiceBusService オブジェクトを作成します。The following code creates a ServiceBusService object that uses the ExponentialRetryPolicyFilter:

var retryOperations = new azure.ExponentialRetryPolicyFilter();
var serviceBusService = azure.createServiceBusService().withFilter(retryOperations);

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

メッセージを Service Bus キューに送信するには、アプリケーションで ServiceBusService オブジェクトの sendQueueMessage メソッドを呼び出します。To send a message to a Service Bus queue, your application calls the sendQueueMessage method on the ServiceBusService object. Service Bus キューに送信された (またキューから受信された) メッセージは BrokeredMessage オブジェクトであり、このオブジェクトには、(LabelTimeToLive などの) 標準的なプロパティ、アプリケーションに特有のカスタム プロパティの保持に使用するディクショナリ、任意のアプリケーション データの本体が備わっています。Messages sent to (and received from) Service Bus queues are BrokeredMessage objects, and have a set of standard properties (such as Label and TimeToLive), a dictionary that is used to hold custom application-specific properties, and a body of arbitrary application data. アプリケーションはメッセージとして文字列値を渡すことでメッセージの本文を設定できます。An application can set the body of the message by passing a string as the message. 必須の標準プロパティには既定値が入力されます。Any required standard properties are populated with default values.

次の例では、sendQueueMessage を使用して、myqueue という名前のキューにテスト メッセージを送信する方法を示しています。The following example demonstrates how to send a test message to the queue named myqueue using sendQueueMessage:

var message = {
    body: 'Test message',
    customProperties: {
        testproperty: 'TestValue'
    }};
serviceBusService.sendQueueMessage('myqueue', message, function(error){
    if(!error){
        // message sent
    }
});

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 つのキューで保持されるメッセージ数には上限がありませんが、1 つのキューで保持できるメッセージの合計サイズには上限があります。There's no limit on the number of messages held in a queue but there's a cap on the total size of the messages held by a queue. このキュー サイズは作成時に定義され、上限は 5 GB です。This queue size is defined at creation time, with an upper limit of 5 GB. クォータの詳細については、「Service Bus のクォータ」を参照してください。For more information about quotas, see Service Bus quotas.

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

キューからメッセージを受信するには、ServiceBusService オブジェクトの receiveQueueMessage メソッドを使用します。Messages are received from a queue using the receiveQueueMessage method on the ServiceBusService object. 既定では、メッセージは読み取られるときにキューから削除されますが、省略可能な isPeekLock パラメーターを true に設定することによって、キューからメッセージを削除せずに、メッセージを読み取って (ピークして) ロックできます。By default, messages are deleted from the queue as they are read; however, you can read (peek) and lock the message without deleting it from the queue by setting the optional parameter isPeekLock to true.

受信操作の過程で行われるメッセージの読み取りと削除の既定動作は、最もシンプルなモデルであり、障害発生時にアプリケーション側でメッセージを処理しないことを許容できるシナリオに最適です。The default behavior of reading and deleting the message as part of the receive operation is the simplest model, and works best for scenarios in which an application can tolerate not processing a message when a failure occurs. この動作を理解するために、コンシューマーが受信要求を発行した後で、メッセージを処理する前にクラッシュしたというシナリオを考えてみましょう。To understand this behavior, 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 before the crash.

isPeekLock パラメーターが true に設定されている場合、受信処理が 2 段階の動作になり、メッセージの紛失が許容できないアプリケーションに対応することができます。If the isPeekLock parameter is set to true, the receive becomes a two stage operation, which makes it possible to support applications that can't 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 receiving it, and then returns it to the application. アプリケーションがメッセージの処理を終えた後 (または後で処理するために確実に保存した後)、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 calling deleteMessage method and providing the message to be deleted as a parameter. deleteMessage メソッドによって、メッセージが読み取り中としてマークされ、キューから削除されます。The deleteMessage method marks the message as being consumed and removes it from the queue.

次の例は receiveQueueMessage を使用してメッセージを受信し、処理する方法を示しています。The following example demonstrates how to receive and process messages using receiveQueueMessage. この例では、最初にメッセージを受信して削除し、次に true に設定した isPeekLock を使用してメッセージを受信した後、deleteMessage を使用してメッセージを削除します。The example first receives and deletes a message, and then receives a message using isPeekLock set to true, then deletes the message using deleteMessage:

serviceBusService.receiveQueueMessage('myqueue', function(error, receivedMessage){
    if(!error){
        // Message received and deleted
    }
});
serviceBusService.receiveQueueMessage('myqueue', { isPeekLock: true }, function(error, lockedMessage){
    if(!error){
        // Message received and locked
        serviceBusService.deleteMessage(lockedMessage, function (deleteError){
            if(!deleteError){
                // Message deleted
            }
        });
    }
});

アプリケーションのクラッシュと読み取り不能のメッセージを処理する方法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. 受信側のアプリケーションが何らかの理由によってメッセージを処理できない場合には、ServiceBusService オブジェクトの unlockMessage メソッドを呼び出すことができます。If a receiver application is unable to process the message for some reason, then it can call the unlockMessage method on the ServiceBusService object. これにより、Service Bus によってキュー内のメッセージはロックが解除され、再度受信できる状態になります。受信するアプリケーションは、以前と同じものでも、別のものでもかまいません。it 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's 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 method is called, then the message will be redelivered to the application when it restarts. この方法は一般に 1 回以上の処理と呼ばれます。つまり、すべてのメッセージが 1 回以上処理されますが、特定の状況では、同じメッセージが再配信される可能性があります。This approach is often called At Least Once Processing, that is, each message will be processed at least once but in certain situations the same message may be redelivered. 重複処理が許されないシナリオの場合は、重複メッセージの配信を扱うロジックをアプリケーションに追加する必要があります。If the scenario can't tolerate duplicate processing, then application developers should add additional logic to their application to handle duplicate message delivery. それは通常、メッセージの MessageId プロパティを使用して対処します。これは配信が試行された後も同じ値を保持します。It's often achieved using the MessageId property of the message, which will remain 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

キューの詳細については、次のリソースを参照してください。To learn more about queues, see the following resources.