Microsoft Azure Queue API
Nach oben zu Azure- und Cloud-Computing mit DataSnap
Warnung: Die DSAzure-API ist veraltet und wurde durch die Data.Cloud.AzureAPI ersetzt. Es wird empfohlen, die neue API für die Entwicklung von Cloud-Computing-Anwendungen zu verwenden. Weitere Informationen finden Sie unter Cloud-Computing mit DataSnap.
Die Microsoft Azure Queue API befindet sich in der Unit DSAzure in der Klasse TAzureQueueService. Ein Beispiel dazu, wie die API verwendet wird, finden Sie im Abschnitt "implementation" der Unit DSAzureQueue. Diese visuelle Komponente verwendet die API.
Inhaltsverzeichnis
Zu den verfügbaren Funktionen zählen: Auflisten der verfügbaren Queues, Erstellen einer Queue, Löschen einer Queue, Ermitteln der Metadaten für eine Queue, Setzen der Metadaten für eine Queue, Hinzufügen einer Nachricht zu einer Queue, Entfernen einer Nachricht aus einer Queue und Löschen aller Queue-Nachrichten.
Die folgenden Anweisungen setzten voraus, dass Sie bereits eine Instanz von TAzureQueueService erstellt haben. In den Codefragmenten wird diese Instanz mit FQueueService bezeichnet. Darüber hinaus wird vorausgesetzt, dass Sie über einen XML-Parser verfügen und dass dieser bereits entsprechend konfiguriert ist. Die API gibt in einigen Fällen XML-Code zurück. Sie müssen in der Lage sein, XML-Code zu analysieren.
Auflisten der verfügbaren Queues
Um die verfügbaren Queues aufzulisten, gehen Sie folgendermaßen vor:
xml := FQueueService.ListQueues([],[]);
Sie erhalten nun eine XML-Antwort, die etwa folgendermaßen aussieht:
<EnumerationResults AccountName="...">
...
<Queues>
<Queue>
<Name>queue-name</Name>
<Url>queue-address</Url>
</Queue>
...
Erstellen einer Queue
Führen Sie zum Erstellen einer Queue den folgenden Aufruf aus:
FQueueService.CreateQueue('queue-name');
Der Queue-Name muss den folgenden Konventionen entsprechen:
- Der Name muss mindestens drei Zeichen lang sein.
- Der Name darf nur Buchstaben, Zahlen und Bindestriche enthalten.
- Der Name darf nicht mit einem Bindestrich beginnen.
- Der Name muss in Kleinbuchstaben geschrieben sein.
Löschen einer Queue
Zum Löschen einer Queue rufen Sie einfach Folgendes auf:
FQueueService.DeleteQueue('queue-name');
Wenn das Löschen erfolgreich war, wird True zurückgegeben. Das Löschen auf dem Server kann etwas dauern. Wenn Sie eine neue Queue mit demselben Namen wie die gerade gelöschte erstellen, könnte diese Aktion daher fehlschlagen.
Ermitteln der Metadaten für eine Queue
Um einen Metadatenwert aus einer Queue zu lesen, können Sie folgendermaßen vorgehen:
if FQueueService.GetQueueMetadata('queue-name') then
begin
Result := FQueueService.ResponseHeader['metadata-key-name'];
end;
Der erste Aufruf von GetQueueMetadata gibt True oder False zurück, je nachdem, ob die Metadaten erfolgreich aufgerufen werden konnten oder nicht. Zum Lesen der eigentlichen Metadaten greifen Sie auf die Eigenschaft ResponseHeader der Dienstinstanz zu.
Setzen der Metadaten für eine Queue
Zum Bearbeiten der Metadaten der Queue können Sie FQueueService aufrufen. PutQueueMetadata('queue-name', MetaData), wobei MetaData eine TStringList mit Schlüssel/Wert-Paaren ist.
Ermitteln der Nachrichten einer Queue
Um die Nachrichten einer Queue mit dem Namen queue-name zu ermitteln, ohne die Nachrichten aus der Queue zu entfernen, gehen Sie folgendermaßen vor:
xml := FQueueService.PeekMessages('queue-name', MsgRetrieveNum);
MsgRetrieveNum ist hier eine Ganzzahl von 1 bis 32. Wenn ein Wert kleiner 1 übergeben wird, gibt der Server eine einzelne Nachricht zurück. Wenn ein Wert größer als 32 angegeben wird, kann dies zu unzuverlässigen Ergebnissen führen, sollte aber im Allgemeinen die maximale Anzahl von Nachrichten (32) zurückgeben.
Der zurückgegebene XML-Code sieht folgendermaßen aus:
<QueueMessagesList>
<QueueMessage>
<MessageId>message-id</MessageId>
<InsertionTime>insertion-time</InsertionTime>
<ExpirationTime>expiration-time</ExpirationTime>
<DequeueCount>integer</DequeueCount>
<MessageText>queue-message-string</MessageText>
</QueueMessage>
</QueueMessagesList>
Es ist wichtig, die Referenz auf die Nachrichten-ID (MessageId) für die spätere Verwendung zu protokollieren, da damit die spezifische Nachricht identifiziert wird. Dies ist beispielsweise für das Löschen der einzelnen Queue-Nachricht erforderlich.
Wenn Sie überprüfen möchten, ob die Queue mehr als die zurückgegebene Anzahl an Nachrichten enthält, können Sie die Gesamtanzahl der Nachrichten in der Queue folgendermaßen abfragen:
if FQueueService.GetQueueMetadata('queue-name') then
begin
ValS := FQueueService.ResponseHeader['x-ms-approximate-messages-count'];
Result := StrToInt(ValS);
end;
Löschen von Nachrichten aus einer Queue
Sie können entweder eine einzelne Nachricht oder alle Nachrichten löschen. Zum Löschen einer einzelnen Nachricht müssen Sie diese zunächst ermitteln (Get). Sie erhalten so ein PopReceipt und können dann damit die spezifische Nachricht löschen. Der Code dafür sieht etwa folgendermaßen aus:
xml := FQueueService.GetMessages('queue-name', 1);
popReceipt := FQueueService.GetPopReceipt(xml);
if popReceipt <> EmptyStr then
Success := FQueueService.DeleteMessage('queue-name', MessageId, popReceipt);
Die MessageId ist dieselbe, die im XML-Code beim Ermitteln der Liste der Queue-Nachrichten zurückgegeben wurde. Beim Aufruf von GetMessages übergeben Sie den Wert 1, was bewirkt, dass nur die oberste Nachricht entfernt wird.
Sie können auch alle Nachrichten in einer Queue löschen, ohne die Queue selbst zu löschen. Verwenden Sie dazu den folgenden Code:
Success := FQueueService.ClearMessages('queue-name');
Wenn die Aktion erfolgreich war, wird true, ansonsten false zurückgegeben.
Hinzufügen einer Nachricht zu einer Queue
Um einer Queue eine Nachricht hinzuzufügen, führen Sie einfach den folgenden Aufruf aus:
Success := FQueueService.PutMessage('queue-name', MessageString);
MessageString ist hier der String, der in der Nachricht gespeichert werden soll.