Microsoft Azure キュー API
Azure と DataSnap でのクラウド コンピューティング への移動
警告： DSAzure API は非推奨になり、Data.Cloud.AzureAPI に置き換えられました。クラウド コンピューティング アプリケーションの開発時には、新しい API を使用することをお勧めします。詳細は、「DataSnap でのクラウド コンピューティング」を参照してください。
Microsoft Azure キュー API は DSAzure ユニット内の TAzureQueueService クラスにあります。使用されている API の例については、DSAzureQueue ユニットの implementation セクションをご覧ください。このユニットは、同 API を使用しているビジュアル コンポーネントです。
目次
提供されている機能には、使用可能なキューの一覧表示、キューの作成、キューの削除、キューのメタデータの取得、キューのメタデータの設定、キューへのメッセージの追加、キューからのメッセージの削除、すべてのキュー メッセージのクリアなどがあります。
以下の説明では、TAzureQueueService のインスタンスを既に作成してあると仮定します。どのコード スニペット（断片）でも、このインスタンスは FQueueService という名前で参照されます。さらに、XML パーサーが手元にあり、使用できるように既に適切に構成されているものとします。API は、場合によっては XML を返しますが、その場合、その XML の解析方法がわかっている必要があります。
使用可能なキューの一覧表示
使用可能なキューを一覧表示するには、以下を行います。
xml := FQueueService.ListQueues([],[]);
その結果、たとえば以下のような XML 応答が返されます。
<EnumerationResults AccountName="...">
...
<Queues>
<Queue>
<Name>queue-name</Name>
<Url>queue-address</Url>
</Queue>
...
キューの作成
キューを新規作成するには、以下を呼び出します。
FQueueService.CreateQueue('queue-name');
キュー名（上記の queue-name）は、以下の命名規則に従っている必要があります。
- 3 文字以上の長さである。
- アルファベット、数字、ハイフンのみで構成されている。
- ハイフン以外で始まる。
- すべて小文字である。
キューの削除
キューを削除するには、以下を呼び出すだけです。
FQueueService.DeleteQueue('queue-name');
その結果、削除が正常に終了した場合は True が返されます。サーバー上での削除には少し時間がかかる場合があるため、削除したばかりのキューと同じ名前のキューを新規作成しようとすると、作成が失敗することがあります。
キューのメタデータの読み取り
キューからメタデータ値を読み取るには、以下を行います。
if FQueueService.GetQueueMetadata('queue-name') then
begin
Result := FQueueService.ResponseHeader['metadata-key-name'];
end;
冒頭の GetQueueMetadata の呼び出しでは、メタデータの取得に成功したかどうかに応じて、True か False が返されます。実際のメタデータを読み取るには、サービス インスタンスの ResponseHeader プロパティにアクセスします。
キューのメタデータの書き込み
キューのメタデータを変更するには、FQueueService.PutQueueMetadata('queue-name', MetaData) を呼び出します。ここで、MetaData はキーと値のペアの TStringList です。
キューのメッセージの取得
queue-name という名前のキューからメッセージを削除せずに取得するには、以下を行います。
xml := FQueueService.PeekMessages('queue-name', MsgRetrieveNum);
ここで、MsgRetrieveNum は 1 ～ 32 の整数です。1 未満の値が渡された場合、サーバーはメッセージを 1 つだけ返します。32 より大きい値が渡された場合は、得られた結果が信頼できないおそれがありますが、一般に最大の数（32 個）のメッセージが返されるはずです。
以下のような XML が返されます。
<QueueMessagesList>
<QueueMessage>
<MessageId>message-id</MessageId>
<InsertionTime>insertion-time</InsertionTime>
<ExpirationTime>expiration-time</ExpirationTime>
<DequeueCount>integer</DequeueCount>
<MessageText>queue-message-string</MessageText>
</QueueMessage>
</QueueMessagesList>
MessageId への参照を後で使用できるように保持しておくことが大切です。メッセージを特定するのにメッセージ ID が使用されるからです。たとえば、単一のキュー メッセージを削除するのに、これが必要です。
返されたメッセージより多くのメッセージがキューに含まれているかどうかを確かめる場合は、以下のようにして、キュー内のメッセージの総数をクエリすることができます。
if FQueueService.GetQueueMetadata('queue-name') then
begin
ValS := FQueueService.ResponseHeader['x-ms-approximate-messages-count'];
Result := StrToInt(ValS);
end;
キューからのメッセージの削除
メッセージを削除する場合は、メッセージを 1 つだけ削除するか、すべて削除するかを選択できます。メッセージを 1 つだけ削除するには、まず、それを取得する必要があります。その際に PopReceipt が得られるので、それを使用して特定のメッセージを削除できます。以下のようなコードになります。
xml := FQueueService.GetMessages('queue-name', 1);
popReceipt := FQueueService.GetPopReceipt(xml);
if popReceipt <> EmptyStr then
Success := FQueueService.DeleteMessage('queue-name', MessageId, popReceipt);
MessageId は、キュー メッセージのリストを取得したときに、返された XML に含まれていた MessageId と同じものです。コードを見れば、GetMessages を呼び出す際に値 1 を渡しているのがわかります。これは、先頭のメッセージのみ取り出すことを指定しています。
また、キューそのものを削除せずにキュー内のメッセージをすべて削除することもできます。それには、次のコードを使用します。
Success := FQueueService.ClearMessages('queue-name');
操作が成功すれば True が返され、そうでない場合は False が返されます。
キューへのメッセージの追加
新しいメッセージをキューに追加するには、以下を呼び出すだけです。
Success := FQueueService.PutMessage('queue-name', MessageString);
ここで、MessageString は、メッセージに格納する文字列です。