API des files Microsoft Azure
Remonter à Environnement Azure et Cloud avec DataSnap
Avertissement : L'API DSAzure est devenue obsolète et a été remplacée par Data.Cloud.AzureAPI. Nous vous encourageons à utiliser la nouvelle API lors du développement d'applications d'environnement cloud. Pour de plus amples informations, voir Environnement Cloud avec DataSnap.
L'API des files Microsoft Azure est située dans l'unité DSAzure, dans la classe TAzureQueueService. Pour obtenir un exemple de l'API utilisée, consultez la section implementation de l'unité DSAzureQueue, qui est le composant visuel utilisant l'API.
Sommaire
Les fonctions disponibles sont les suivantes : le listage des files disponibles, la création d'une file, la suppression d'une file, l'obtention des métadonnées d'une file, la définition des métadonnées d'une file, l'ajout d'un message dans une file, le retrait d'un message d'une file et l'effacement de tous les messages de la file.
Les instructions suivantes supposent que vous avez déjà créé une instance de TAzureQueueService. Dans les extraits de code, cette instance sera référencée comme FQueueService. Il est aussi supposé que vous avez un analyseur XML à disposition et qu'il est déjà configuré de façon appropriée. L'API renvoie dans certains cas un XML, que vous devez savoir analyser.
Listage des files disponibles
Pour lister les files disponibles, procédez comme suit :
xml := FQueueService.ListQueues([],[]);
Vous devez maintenant avoir une réponse XML, comme celle-ci :
<EnumerationResults AccountName="...">
...
<Queues>
<Queue>
<Name>queue-name</Name>
<Url>queue-address</Url>
</Queue>
...
Création d'une file
Pour créer une nouvelle file, appelez :
FQueueService.CreateQueue('queue-name');
Le paramètre queue-name doit adhérer à quelques conventions de nommage :
- Le nom doit avoir une longueur d'au moins trois caractères.
- Le nom peut seulement inclure des lettres, des nombres et des traits d'union.
- Le nom ne doit pas commencer par un trait d'union.
- Le nom doit être en minuscules.
Suppression d'une file
Pour supprimer une file, appelez simplement :
FQueueService.DeleteQueue('queue-name');
Ceci renvoie True si la suppression a réussi. La suppression sur le serveur peut prendre quelques instants. Ainsi, si vous essayez de créer une nouvelle file avec le nom de la file que vous venez juste de supprimer, cette action peut échouer.
Lecture des métadonnées d'une file
Pour lire la valeur des métadonnées d'une file, exécutez l'instruction suivante :
if FQueueService.GetQueueMetadata('queue-name') then
begin
Result := FQueueService.ResponseHeader['metadata-key-name'];
end;
L'appel initial à GetQueueMetadata renvoie True ou False, selon la réussite ou l'échec de la récupération des métadonnées. Pour lire les métadonnées réelles, accédez à la propriété ResponseHeader de l'instance de service.
Ecriture des métadonnées d'une file
Pour modifier les métadonnées d'une file, vous pouvez appeler FQueueService.PutQueueMetadata('queue-name', MetaData), où MetaData est un TStringList de paires clé / valeur.
Obtention des messages d'une file
Pour obtenir les messages d'une file de nom queue-name sans retirer les messages de la file, exécutez l'instruction suivante :
xml := FQueueService.PeekMessages('queue-name', MsgRetrieveNum);
où MsgRetrieveNum est un entier compris entre 1 et 32. Si une valeur inférieure à 1 est passée, le serveur renvoie un message unique. Si une valeur supérieure à 32 est donnée, ceci pourrait produire des résultats peu fiables, mais devrait en général renvoyer le nombre maximal de messages, c'est-à-dire 32.
Le XML renvoyé devrait ressembler à ceci :
<QueueMessagesList>
<QueueMessage>
<MessageId>message-id</MessageId>
<InsertionTime>insertion-time</InsertionTime>
<ExpirationTime>expiration-time</ExpirationTime>
<DequeueCount>integer</DequeueCount>
<MessageText>queue-message-string</MessageText>
</QueueMessage>
</QueueMessagesList>
Il est important de conserver la référence au MessageId pour un usage ultérieur, car il sera utilisé pour identifier un message spécifique. Par exemple, l'identificateur est nécessaire pour supprimer un message unique de la file.
Si vous voulez savoir si la file contient davantage de messages que le nombre de messages renvoyé, vous pouvez demander le nombre total de messages de la file, comme suit :
if FQueueService.GetQueueMetadata('queue-name') then
begin
ValS := FQueueService.ResponseHeader['x-ms-approximate-messages-count'];
Result := StrToInt(ValS);
end;
Suppression des messages d'une file
Pour supprimer des messages, vous pouvez choisir de supprimer un message unique, ou de supprimer tous les messages. Pour supprimer un message unique, vous devez d'abord l'obtenir (Get), ce qui vous donnera un PopReceipt que vous pourrez utiliser pour supprimer le message spécifique. Le code correspondant devrait ressembler à ceci :
xml := FQueueService.GetMessages('queue-name', 1);
popReceipt := FQueueService.GetPopReceipt(xml);
if popReceipt <> EmptyStr then
Success := FQueueService.DeleteMessage('queue-name', MessageId, popReceipt);
Le MessageId est le même que le MessageId renvoyé dans le XML quand vous avez obtenu la liste des messages de la file. Vous pouvez le constater quand, lors de l'appel à GetMessages, vous passez la valeur 1 qui indique le message supérieur.
Vous pouvez aussi supprimer tous les messages d'une file sans supprimer la file elle-même. Pour ce faire, utilisez le code suivant :
Success := FQueueService.ClearMessages('queue-name');
True est renvoyé si l'action a réussi, false sinon.
Ajout d'un message à une file
Pour ajouter un nouveau message à une file, appelez simplement :
Success := FQueueService.PutMessage('queue-name', MessageString);
où MessageString est la chaîne que vous voulez stocker dans le message.