Windows 8 向けサービス バスのサンプルのご紹介


このポストは、5月23日に投稿された Getting Started with the Service Bus Samples for Windows 8 の翻訳です。

先日、マイクロソフトは Windows Azure Toolkit for Windows 8 (英語) の機能の 1 つとして、Windows 8 の Metro スタイル アプリケーションへのアクセスに使用するためのサンプル ライブラリ、およびサービス バスの基本機能の学習にお使いいただくための Metro スタイル アプリケーションのサンプルをリリースしました。この記事では、このサンプルアプリケーションについて簡単に説明し、サンプル ライブラリの概要を示すとともに、サンプル ライブラリの動作を詳しく検証します。

Windows 8 向けサービス バスのサンプル ブラウザー

先日、マイクロソフトは、サービス バスの機能を気軽に試していただくために Windows 8 向けサービス バスのサンプル ブラウザーを作成しました。これは簡単な Metro スタイル アプリケーションで、コードを細かく確認しながらサービス バスの機能をインタラクティブに体験し、学習することができます。

サンプル ブラウザーで AppBar を表示 (マウスの場合は右クリック、タッチの場合は下のベゼルを上にスワイプ) すると、各サンプルのソースコードをクリップボードにコピーし、Visual Studio に貼り付けて使用できます。

サンプル ブラウザーには、簡単なサンプルが 3 つ用意されています。

単純な Queue 方式
サービス バスのキューは永続的な先入れ先出し方式のメッセージ キューで、分散型アプリケーションまたはコンポーネント間の通信に使用されます。詳しくは、WindowsAzure.com のサービス バスにおけるキューの詳細 (英語) についての記事を参照してください。このキューの動作は単純で、あるユーザーがキューにメッセージを送信し、他のユーザーがそのメッセージを受信するだけです。

上記の単純な Queue のサンプルでは、この簡単なメッセージ処理が Windows 8 Metro スタイル アプリケーションでどのように実行されるかを把握できます。

単純な Topic 方式
サービス バスでは Publish/Subscribe の通信モデルがサポートされていて、トピックの処理とそのメッセージの受信に使用されます。特定のトピックにメッセージが送信され、そのメッセージが複数のユーザーに受信されます。詳しくは、WindowsAzure.com のサービス バスにおけるトピックの詳細 (英語) についての記事を参照してください。Topic の場合も Queue の場合と同様に単純です。あるユーザーが特定のトピックにメッセージを送信し、各受信者がそのメッセージのコピーを受信するだけです。

 

上記の単純な Topic 方式のサンプルでは、まずトピックを作成し、そのトピックに 1 人以上の受信者を追加した後、メッセージの送受信を行います。

Peek/Lock、破棄、完了
Queue と Topic では、それぞれ異なった方法でメッセージを受信していました。Receive/Delete 方式では、メッセージを受信すると同時にそのメッセージがキューまたはサブスクリプションから削除されます。この場合、受信者がメッセージの処理に失敗した場合、そのメッセージの内容は失われます。Peek/Lock 方式では、受信と削除が独立して処理されます。まず、受信者の操作でキューのメッセージがピークされます。次に、そのメッセージの処理を完了 (キューまたはサブスクリプションからメッセージを削除し、処理済みとしてマーク) するか、またはメッセージの処理を破棄 (未完了または未処理としてマーク) するかを受信者が決定します。メッセージの処理が破棄されるか、またはメッセージのピークロックがタイムアウトすると、そのメッセージはキューまたはサブスクリプションに戻されます (ピーク ロックのタイムアウトは、既定では 30 秒です)。

Peek/Lock 方式のサンプルで、この処理を実際にお試しください。それぞれの図形をクリックしてキューに送信し、次に受信します。図形を受信したら、そのメッセージの処理を完了するか、それとも破棄するかを選択します。完了を選択したメッセージはキューに戻されませんが、破棄を選択したメッセージはキューに戻されます。いずれも選択しない場合、ロック処理がタイムアウトして、そのメッセージは自動的にキューに戻されます。

Windows 8 向けサービス バスのサンプル ライブラリ - Microsoft.Samples.ServiceBus

まず、Windows Azure Toolkit for Windows 8 (英語) をダウンロードします。

サービス バスの REST API をより簡単にご活用いただくため、Queue、Topic、Subscription などのサービス バスの基礎的な機能をサポートする、Windows 8 用のサンプル ライブラリを作成しました。以降では、キューの作成、メッセージの送受信、キューの削除について、サンプル コードを使用して具体的に説明します。サービスバスを初めて使用する方は、先にサービス バスのキュー (英語) およびサービス バスのトピック (英語) についての記事をお読みください。

サービス バスの呼び出しには HTTP を使用するので、次の点について考慮する必要があります。

  1. パッケージ マニフェストでインターネット (クライアント) 機能を要求すること: サービス バスはインターネット上に存在します。アプリケーションにネットワークへのアクセス許可が付与されていることを確認してください。
  2. ネットワークの呼び出しは必ず非同期にすること: ネットワークの呼び出しは完了までにある程度の時間を要する場合があるため、非同期 I/O を使用するほうが便利です。そのため、サービス バスのサンプル ライブラリではすべての処理についてシンプルな非同期メソッドをご用意しています。

まず、トークン プロバイダーを用意します。ライブラリはトークン プロバイダーを通じてアクセス制御サービス (ACS) から認証トークンを取得し、サービスバスへの要求にそのトークンを添付します。トークン プロバイダーにはさまざまな資格情報が格納されているため、サービス バスのリソースに対する操作を実行しているユーザーを特定できます。

TokenProvider tokenProvider = TokenProvider.CreateSharedSecretTokenProvider(
        serviceNamespace: "Your Service Bus Namespace Name, e.g. contoso",
        issuerName: "owner",
        issuerSecret: "Your Service Bus Issuer Secret, e.g. b66Gxx...");

次に、キューを作成します。ここで使用する呼び出しは非常に簡単なもので、キューの作成先のパスを指定し、既定の QueueDescription を使用します。作成するキューの設定を変更する場合には、QueueDescription をパラメーターとして指定できる便利なオーバーロードを使用できます。

Queue myQueue = await Queue.CreateAsync("MyQueue", tokenProvider);

これでサービス バスにキューが作成され、メッセージを送信できる状態になりました。次に、プレーン テキスト形式のメッセージまたは JSON 形式のオブジェクトを本文とするメッセージを送信します。これは、サンプル ライブラリを使用すると簡単にできます。ここでは、本文にテキスト文字列を使用したメッセージを非同期的に送信します。

await myQueue.SendAsync("Hello World!");

メッセージの受信も簡単です。Receive/Delete 方式でキューからメッセージを受信します。Peek/Lock 方式で受信する場合は、代わりに PeekLockAsync メソッドを使用します。メッセージ受信後、プレーン テキストの本文を抽出します。

BrokeredMessage message = await myQueue.ReceiveAndDeleteAsync();
string greeting = message.GetBody<string>();

最後に、キューを削除します。

await Queue.DeleteAsync("MyQueue", tokenProvider); 

以上のように、わずか数行のコードで、サービス バス内のエンティティの作成、送受信、削除が可能です。Windows 8 サービス バスのサンプルライブラリは、簡素な API サーフェイスの学習にお使いいただけるだけでなく、必要となれば REST API サーフェイスの機能を完全に活用することもできます。マイクロソフトでは、このライブラリを自由自在にお使いいただけるように、ライセンス付きのオープンソース サンプルとして公開しています。納得がいくまで使い込んで、コードを十分に理解してください。

マイクロソフトでは、Windows 8 向けサービス バスのサンプル ライブラリで提供している簡素化された API サーフェイスが、サービスバスを利用する Metro スタイル アプリケーションの開発にこれから取り組む方々にご活用いただけることを願っています。新たに習得していただく項目の数をできるだけ減らして、まずは一般的なシナリオをご理解いただき、その後は必要に応じて高度な機能を簡単に学習できるようになっています。マイクロソフトでは、このサンプルライブラリに関して、どの程度お役に立ったかなどのフィードバックをお待ちしています。Windows Azure Toolkit for Windows 8 (英語) のディスカッション リストにご意見をお寄せください。

さらに詳しく: Windows 8 向けサービス バスのサンプル ライブラリの動作

サービス バスの処理は、管理とランタイムの 2 つのクラスに分類されます。管理処理では、キュー、トピック、サブスクリプションなどのサービスバス エンティティの作成、列挙、取得、削除が実行されます。ランタイム処理では、メッセージの送受信が実行されます。ここではまず、Windows 8 向けサービスバスのサンプル ライブラリに実装されている管理処理について詳しく説明します。その後、ランタイム処理の実装を簡単に説明します。

管理処理: 作成、取得、列挙、削除
サービス バスの名前空間は、下位のパスに存在するエンティティをそれぞれ記述した ATOM フィードの集合と考えることができます。たとえば、'Foo' という名前のキューが https://contoso.servicebus.windows.net/Foo という URI に存在する場合、このアドレスには次のような ATOM エントリがあります。

 

このコードを見ると、キューのアドレス (3 行目)、キューの名前 (4 行目)、この場所に存在するキューに関する記述 (12 ~ 25 行目) があることがわかります。このパターンは、名前空間全体で共通です。どのようなエンティティも、ATOM エントリにラップされた XML エンティティとして記述されます。

サービス バスのエンティティ管理のため、これらのフィードに対する処理は、サービス バスの名前空間内で HTTPS プロトコルを使用して RESTful に実行されます。エンティティを作成する場合は HTTP PUT、エンティティを取得する場合は HTTP GET、エンティティを削除する場合は HTTP DELETE を発行します。列挙を実行する場合は、名前空間のルートにある予約済みの $Resources コレクション (例: /$Resources/Queues) の内部で HTTP GET を発行します。

作成可能なエンティティおよびサブエンティティの各種タイプは、Resource Description 階層で表されます。おなじみの Queue、Topic、Subscription のほか、Rule Description、Rule Filter、Rule Aciton など、より高度なエンティティがあります。

Resource Description タイプは、サービス バスのエンティティを表す ATOM エントリの内容をカプセル化して保持しています。DataContractSerializer でこれらのタイプを XML に順番に記述し、ATOM エンティティにラップすると、サービスバス内のエンティティの作成、削除、列挙、表示に使用できます。

Windows 8 向けサービス バスのサンプル ライブラリでは、ResourceDescription は AsSyndicationItem() メソッドの呼び出しにより、ATOM エントリとして表されます。SyndicationItem タイプは、RSS フィードと ATOM フィードの両方に使用可能なクラスを提供する System.ServiceModel.Syndication 名前空間内に存在します。同様に、静的な ResourceDescription.Create<T>(SyndicationItem) メソッドを使用し、必要なリソース タイプをタイプ パラメーター T で指定すると、ResourceDescription を ATOM エントリから抽出できます (たとえば、TQueueDescription などに設定します)。

各種のサービス バス エンティティの記述を ResourceDescription としてモデル化する手順、および ResourceDescription.AsSyndicationItem() メソッドと ResourceDescription.Create<T>(SyndicationItem item) メソッドを使用して ATOM との間で変換する手順をご理解いただけたでしょうか。次に、作成、取得、列挙、削除の各処理の実装について説明します。ここでは Queue の場合を例に管理処理の実装を説明しますが、Topic、Subscription、および Rule の場合でも、使用されるロジックはほぼ同じです。

では、キューの作成から始めます。

Queue myQueue = await Queue.CreateAsync("Foo", tokenProvider); 

Queue.CreateAsync を呼び出す際には、次の処理を実行します。

  1. QueueDescription のインスタンスを作成し、そのパスとして "Foo" を指定します。
  2. tokenProvider で指定したサービス バス名前空間内に NamespaceManager を作成します。
  3. NamespaceManager に対し、指定した QueueDescription でのキューの新規作成を要求します。
  4. NamespaceManager の内部で AsSyndicationItem() を呼び出し、QueueDescriptionAtom にラップします。
  5. SyndicationClient に対し、指定した SyndicationItem でのリソースの新規作成を要求します。
  6. SyndicationClientTokenProviderAuthorization Token を要求します。
  7. SyndicationClientHTTP PUT を発行します。このときの本文は SyndicationItem、ヘッダーは Authorization Token です。
  8. SyndicationClient によって HTTP ResponseSyndicationItem に読み込まれます。
  9. SyndicationItemNamespaceManager に戻されます。
  10. NamespaceManagerSyndicationItemContentQueueDescription として抽出します。
  11. QueueDescription が呼び出し側の Queue.CreateAsync メソッドに戻されます。
  12. Queue のインスタンスが作成され、新しく作成した QueueDescription がカプセル化されます。

foo という名前のキューを作成するという過程において、要求がサービス バスへ渡されるまでに、QueueNamespaceManagerSyndicationClient がそれぞれ情報のレイヤーとして追加されていく様子をイメージしていただけたと思います。

 

Queue クラスは、QueueDescription のほかに Send/Receive などの処理も 1 か所にカプセル化するため、便利に使用できます。Queue タイプは、NamespaceManager を使用してサービス バス名前空間内のエンティティの作成、列挙、取得、削除を実行します。NamespaceManager は、ServiceBusEnvironment を使用して HTTP 要求の発行先となる絶対 URI を明示し、AsSyndicationItem メソッドで ResourceDescription を ATOM にラップし、SyndicationClient で HTTP 呼び出しを作成します。SyndicationClient は、TokenProvider で認証トークンを取得し、HTTPClient で HTTP 呼び出しを作成します。

管理処理のしくみは、すべて同じです。これらの処理は最初、Queue、Topic、Subsctiption などのハイレベルなアブストラクションに対して発行されます。次に、名前空間マネージャーに引き渡されてアドレス指定と ATOM への変換が行われ、さらに配信クライアントが処理し、サービス バスに対して生の HTTP 要求が実行されます。

ランタイム処理: 送信、受信、ピーク ロック、破棄、完了
HTTP でのメッセージの送受信は、非常に単純です。メッセージを送信するには、キューまたはトピックの 'messages' コレクションに HTTP POST を発行します。Receive/Delete モードでメッセージを受信する場合は、キューまたはサブスクリプションの 'messages' コレクションの先頭で HTTP DELETE を発行します。ピーク ロックの場合も同様です。まず 'messages' コレクションの先頭で HTTP POST を発行してピーク ロックを実行します。その後、ロックした場所に対して HTTP PUT を発行した場合はメッセージ処理を破棄し、HTTP DELETE を発行した場合は処理を完了します。

サービス バス メッセージには、ヘッダー (送信時刻、メッセージ ID、有効期限など)、ユーザー指定のメッセージ プロパティ、および本文で構成されています。HTTP で送信する場合、ヘッダーは BrokerProperties という名前の予約済み HTTP ヘッダーに JSON 形式でカプセル化され、ユーザー指定のメッセージプロパティはプレーン テキスト形式で HTTP ヘッダーにカプセル化されます。サービス バス メッセージの本文は HTTP メッセージの本文です。キューへのメッセージの送信は、そのキューに対して SendAsync を呼び出す場合と同じように簡単です。

await myQueue.SendAsync("Hello, World!"); 

このメッセージを送信した場合の HTTP の処理手順を説明します。

POST https://contoso.servicebus.windows.net/Foo/Messages HTTP/1.1
Host: contoso.servicebus.windows.net
Authorization: WRAP access_token="..."
Content-Type: text/plain
Content-Length: 13

Hello, World!

メッセージの受信も同じように単純です。この場合、受信と削除はキューの先頭から順に実行されます。

BrokeredMessage message = await myQueue.ReceiveAndDeleteAsync();

このときの HTTP の要求および応答の処理手順は、次のとおりです。

DELETE https://contoso.servicebus.windows.net/Foo/Messages/Head?timeout=30 HTTP/1.1
Host: contoso.servicebus.windows.net
Authorization: WRAP access_token="..."
Content-Length: 0

-

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/plain
Server: Microsoft-HTTPAPI/2.0
BrokerProperties: {"DeliveryCount":1,"MessageId":"62a7eceab7eb4d52ac741af5f44393ce","SequenceNumber":1,"TimeToLive":922337203685.47754}
Date: Mon, 04 Aug 2015 16:23:42 GMT

Hello, World!

ここまでの説明で、簡単な形式の HTTP でのサービス バス メッセージ処理、および BrokerProperties ヘッダーで使用可能なメタデータの一部についておわかりいただけたことと思います。Windows 8 向けサービス バスのサンプル ライブラリでは、BrokeredMessage タイプがサービス バス メッセージとそのヘッダー、プロパティ、および本文のカプセル化に使用されています。次に、SendAsync の呼び出し処理の流れを説明します。

  1. SendAsync(string ) を呼び出し、サービス バス メッセージをプレーン テキスト形式で送信することを明示します。
  2. 新しい BrokeredMessage が構築され、メッセージの本文が Stream に書き込まれます。
  3. キューが、新しく構築されたメッセージを使用して MessageSender に対する SendAsync(BrokeredMessage) を呼び出します。
  4. MessageSenderTokenProvider を使用して Authorization Token を要求します。
  5. MessageSender が、BrokeredMessage の BodyStream を本文に指定し HTTP POST を発行します。
  6. BrokerProperties、ユーザー指定のメッセージ プロパティ、および Authorization Header を含む HTTP ヘッダーが要求に添付されます。
  7. HTTP Response が OK (200) のステータス コードであるかどうかがチェックされます。

この例よりも複雑な場合でも、JSON 形式にシリアル化すると、メッセージの本文として MessageSender で送信できます。キューまたはサブスクリプションからのメッセージの受信は、MessageReceiver を使用して同様の方法で実行します。

以上、Windows 8 向けサービス バスのサンプル ライブラリについて駆け足でご紹介しましたが、初歩を理解するうえで参考になりましたでしょうか。マイクロソフトは、このライブラリに対するフィードバックをお待ちしています。また、このライブラリを利用して、秀逸なアプリケーションが構築されることを期待しています。その際には、Windows Azure Toolkit for Windows 8 (英語) のディスカッション リストでお知らせください。

Comments (0)

Skip to main content