Démarrage rapide : Bibliothèque de client Stockage File d’attente Azure pour JavaScript

Familiarisez-vous avec la bibliothèque de client Storage File d’attente Azure pour JavaScript. Le Stockage File d’attente Azure est un service permettant de stocker un grand nombre de messages dans le but de les récupérer et de les traiter plus tard. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base.

Documentation de référence sur les API | Code source de la bibliothèque | Package (npm) | Exemples

Utilisez la bibliothèque de client Stockage File d’attente Azure pour JavaScript afin d’effectuer les opérations suivantes :

• Créer une file d’attente
• Ajouter des messages à une file d’attente
• Afficher un aperçu des messages d’une file d’attente
• Mettre à jour un message dans une file d’attente
• Obtention de la longueur de la file d'attente
• Recevoir les messages d’une file d’attente
• Supprimer des messages d’une file d’attente
• Suppression d'une file d'attente

Prérequis

• Abonnement Azure : créez-en un gratuitement
• Compte de stockage Azure : créez un compte de stockage
• Node.js actuel pour votre système d’exploitation.

Configuration

Cette section vous guide tout au long de la préparation d’un projet à utiliser avec la bibliothèque de client Stockage File d’attente Azure pour JavaScript.

Créer le projet

Créez une application Node.js nommée queues-quickstart.

1. Dans une fenêtre de console (telle que cmd, PowerShell ou Bash), créez un nouveau répertoire pour le projet :

   mkdir queues-quickstart
   

2. Basculez vers le répertoire queues-quickstart créé :

   cd queues-quickstart
   

3. Créez un package.json :

   npm init -y
   

4. Ouvrez le projet dans Visual Studio Code :

   code .
   

Installer les packages

À partir du répertoire du projet, installez les packages suivants à l’aide de la commande npm install.

1. Installer le package npm Stockage File d'attente Azure :

   npm install @azure/storage-queue
   

2. Installez le package npm Azure Identity pour prendre en charge les connexions sans mot de passe :

   npm install @azure/identity
   

3. Installer d’autres dépendances utilisées dans ce démarrage rapide :

   npm install uuid dotenv
   

Configurer le framework d’application

À partir du répertoire de projet :

1. Ouvrez un nouveau fichier texte dans votre éditeur de code

2. Ajouter des appels require pour charger des modules Azure et Node.js

3. Créer la structure du programme, y compris la gestion des exceptions de base

   Voici le code :

   const { QueueClient } = require("@azure/storage-queue");
   const { DefaultAzureCredential } = require('@azure/identity');
   const { v1: uuidv1 } = require("uuid");
   
   async function main() {
       console.log("Azure Queue Storage client library - JavaScript quickstart sample");
   
       // Quickstart code goes here
   }
   
   main().then(() => console.log("\nDone")).catch((ex) => console.log(ex.message));
   
   

4. Enregistrez le nouveau fichier sous index.js dans le répertoire queues-quickstart.

Authentification auprès d’Azure

Les requêtes d’application vers les Services Azure doivent être autorisées. L’utilisation de la classe DefaultAzureCredential fournie par la bibliothèque de client Azure Identity est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code.

Vous pouvez également autoriser directement les requêtes adressées aux services Azure à l’aide de mots de passe, de chaînes de connexion ou d’autres informations d’identification. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer les secrets dans un emplacement non sécurisé. Toute personne ayant accès au mot de passe ou à la clé secrète est en mesure de s’authentifier. DefaultAzureCredential offre des avantages améliorés en matière de gestion et de sécurité par rapport à la clé de compte pour autoriser l’authentification sans mot de passe. Les deux options sont illustrées dans l’exemple suivant.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Modèle objet

Stockage File d’attente Azure est un service permettant de stocker un grand nombre de messages. La taille maximale d’un message de file d’attente est de 64 Ko. Une file d’attente peut contenir des millions de messages, dans la limite de la capacité totale d’un compte de stockage. Les files d’attente sont couramment utilisées pour créer un backlog de travail à traiter de façon asynchrone. Le Stockage File d’attente offre trois types de ressources :

• Compte de stockage : Tous les accès à Azure Storage passent par un compte de stockage. Pour plus d’informations sur les comptes de stockage, consultez Vue d’ensemble des comptes de stockage.
• File d’attente : une file d’attente contient un ensemble de messages. Tous les messages doivent être dans une file d’attente. Notez que le nom de la file d’attente doit être en minuscules. Pour plus d'informations sur l’affectation de noms à des files d’attente, consultez Affectation de noms pour les files d'attente et les métadonnées.
• Message : message dans n’importe quel format d’une taille maximale de 64 Ko. Un message peut rester dans la file d’attente pendant un maximum de 7 jours. Pour les versions du 29 juillet 2017 ou ultérieures, la durée de vie maximale peut être n’importe quel nombre positif, ou -1 indiquant que le message n’expire pas. Si ce paramètre est omis, la valeur par défaut de la durée de vie est de sept jours.

Le diagramme suivant montre la relation entre ces ressources.

Utilisez les classes JavaScript suivantes pour interagir avec ces ressources :

• QueueServiceClient : une instance QueueServiceClient représente une connexion à un compte de stockage donné dans le service de File d’attente Stockage Azure. Ce client vous permet de gérer toutes les files d’attente de votre compte de stockage.
• QueueClient : une instance QueueClient représente une file d’attente unique dans un compte de stockage. Ce client vous permet de gérer et de manipuler une file d’attente individuelle et ses messages.

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les actions suivantes avec la bibliothèque de client Stockage File d’attente Azure pour JavaScript :

• Autoriser l’accès et créer un objet client
• Créer une file d’attente
• Ajouter des messages à une file d’attente
• Afficher un aperçu des messages d’une file d’attente
• Mettre à jour un message dans une file d’attente
• Obtention de la longueur de la file d'attente
• Recevoir les messages d’une file d’attente
• Supprimer des messages d’une file d’attente
• Supprimer une file d’attente

az login

az login

Connect-AzAccount

const { DefaultAzureCredential } = require('@azure/identity');

// Create a unique name for the queue
const queueName = "quickstart" + uuidv1();

// Instantiate a QueueClient which will be used to create and interact with a queue
// TODO: replace <storage-account-name> with the actual name
const queueClient = new QueueClient(`https://<storage-account-name>.queue.core.windows.net/${queueName}`, new DefaultAzureCredential());

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be
// closed and reloaded to take the environment variable into account.
const AZURE_STORAGE_CONNECTION_STRING = process.env.AZURE_STORAGE_CONNECTION_STRING;

// Create a unique name for the queue
const queueName = "quickstart" + uuidv1();

// Instantiate a QueueClient which will be used to create and interact with a queue
const queueClient = new QueueClient(AZURE_STORAGE_CONNECTION_STRING, queueName);

Les messages des files d’attente sont stockés sous forme de chaînes. Si vous devez envoyer un autre type de données, vous devez le sérialiser dans une chaîne lors de l’envoi du message et désérialiser le format de chaîne lors de la lecture du message.

Pour convertir JSON au format chaîne et revenir à nouveau dans Node.js, utilisez les fonctions d’assistance suivantes :

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

Créer une file d’attente

Avec l’objet QueueClient, appelez la méthode create pour créer la file d’attente dans votre compte de stockage.

Ajoutez ce code à la fin de la méthode main :

console.log("\nCreating queue...");
console.log("\t", queueName);

// Create the queue
const createQueueResponse = await queueClient.create();
console.log("Queue created, requestId:", createQueueResponse.requestId);

Ajouter des messages à une file d’attente

L’extrait de code suivant ajoute des messages à la file d’attente en appelant la méthode sendMessage. Il enregistre également le QueueSendMessageResponse retourné par le troisième appel de sendMessage. Le sendMessageResponse retourné est utilisé pour mettre à jour le contenu du message ultérieurement dans le programme.

Ajoutez ce code à la fin de la fonction main :

console.log("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.sendMessage("First message");
await queueClient.sendMessage("Second message");
const sendMessageResponse = await queueClient.sendMessage("Third message");

console.log("Messages added, requestId:", sendMessageResponse.requestId);

Afficher un aperçu des messages d’une file d’attente

Affichez un aperçu des messages de la file d’attente en appelant la méthode peekMessages. Cette méthode récupère un ou plusieurs messages du début de la file d’attente, mais ne modifie pas la visibilité du message. Par défaut, peekMessages lit furtivement un seul message.

Ajoutez ce code à la fin de la fonction main :

console.log("\nPeek at the messages in the queue...");

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages : 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("\t", peekedMessages.peekedMessageItems[i].messageText);
}

Mettre à jour un message dans une file d’attente

Mettez à jour le contenu d’un message en appelant la méthode updateMessage. Cette méthode peut changer le contenu et le délai d’expiration de la visibilité d’un message. Le contenu du message doit être une chaîne encodée en UTF-8 d’une taille maximale de 64 Ko. Avec le nouveau contenu, transmettez messageId et popReceipt à partir de la réponse qui a été enregistrée dans le code. Les propriétés sendMessageResponse identifient le message à mettre à jour.

console.log("\nUpdating the third message in the queue...");

// Update a message using the response saved when calling sendMessage earlier
updateMessageResponse = await queueClient.updateMessage(
    sendMessageResponse.messageId,
    sendMessageResponse.popReceipt,
    "Third message has been updated"
);

console.log("Message updated, requestId:", updateMessageResponse.requestId);

Obtention de la longueur de la file d'attente

La méthode getProperties renvoie des métadonnées sur la file d’attente, notamment le nombre approximatif de messages en attente dans la file d’attente.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

Réception des messages d'une file d'attente

Téléchargez les messages ajoutés en appelant la méthode receiveMessages. Dans le champ numberOfMessages, transmettez le nombre maximal de messages à recevoir pour cet appel.

Ajoutez ce code à la fin de la fonction main :

console.log("\nReceiving messages from the queue...");

// Get messages from the queue
const receivedMessagesResponse = await queueClient.receiveMessages({ numberOfMessages : 5 });

console.log("Messages received, requestId:", receivedMessagesResponse.requestId);

Lorsque vous appelez la méthode receiveMessages, vous pouvez éventuellement spécifier des valeurs dans QueueReceiveMessageOptions pour personnaliser la récupération des messages. Vous pouvez spécifier une valeur pour numberOfMessages, qui est le nombre de messages à récupérer à partir de la file d’attente. La valeur par défaut est de 1 message et la valeur maximale est de 32 messages. Vous pouvez également spécifier une valeur pour visibilityTimeout, qui masque les messages aux autres opérations pendant la période d’expiration. La valeur par défaut est 30 secondes.

Supprimer des messages d’une file d’attente

Vous pouvez supprimer les messages de la file d’attente une fois qu’ils sont reçus et traités. Dans ce cas, le traitement affiche simplement le message sur la console.

Supprimez les messages en appelant la méthode deleteMessage. Les messages qui ne sont pas supprimés explicitement redeviennent visibles dans la file d’attente et peuvent éventuellement être de nouveau traités.

Ajoutez ce code à la fin de la fonction main :

// 'Process' and delete messages from the queue
for (i = 0; i < receivedMessagesResponse.receivedMessageItems.length; i++) {
    receivedMessage = receivedMessagesResponse.receivedMessageItems[i];

    // 'Process' the message
    console.log("\tProcessing:", receivedMessage.messageText);

    // Delete the message
    const deleteMessageResponse = await queueClient.deleteMessage(
        receivedMessage.messageId,
        receivedMessage.popReceipt
    );
    console.log("\tMessage deleted, requestId:", deleteMessageResponse.requestId);
}

Suppression d'une file d'attente

Le code suivant nettoie les ressources créées par l’application en supprimant la file d’attente avec la méthode delete.

Ajoutez ce code à la fin de la fonction main et enregistrez le fichier :

// Delete the queue
console.log("\nDeleting queue...");
const deleteQueueResponse = await queueClient.delete();
console.log("Queue deleted, requestId:", deleteQueueResponse.requestId);

Exécuter le code

Cette application crée trois messages et les ajoute à une file d’attente Azure. Le code liste les messages dans la file d’attente, puis les récupère et les supprime avant de supprimer la file d’attente.

Dans la fenêtre de votre console, accédez au répertoire contenant le fichier index.js, puis utilisez la commande node suivante pour exécuter l’application.

node index.js

La sortie de l’application ressemble à l’exemple suivant :

Azure Queue Storage client library - JavaScript quickstart sample

Creating queue...
         quickstart<UUID>
Queue created, requestId: 5c0bc94c-6003-011b-7c11-b13d06000000

Adding messages to the queue...
Messages added, requestId: a0390321-8003-001e-0311-b18f2c000000

Peek at the messages in the queue...
         First message
         Second message
         Third message

Updating the third message in the queue...
Message updated, requestId: cb172c9a-5003-001c-2911-b18dd6000000

Receiving messages from the queue...
Messages received, requestId: a039036f-8003-001e-4811-b18f2c000000
        Processing: First message
        Message deleted, requestId: 4a65b82b-d003-00a7-5411-b16c22000000
        Processing: Second message
        Message deleted, requestId: 4f0b2958-c003-0030-2a11-b10feb000000
        Processing: Third message has been updated
        Message deleted, requestId: 6c978fcb-5003-00b6-2711-b15b39000000

Deleting queue...
Queue deleted, requestId: 5c0bca05-6003-011b-1e11-b13d06000000

Done

Parcourez le code dans le débogueur et vérifiez votre portail Azure tout au long du processus. Vérifiez votre compte de stockage pour vous assurer que les messages de la file d’attente sont créés et supprimés.

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez appris à créer une file d’attente et à y ajouter des messages à l’aide de code JavaScript. Ensuite, vous avez appris à afficher un aperçu des messages, à les récupérer et à les supprimer. Enfin, vous avez appris à supprimer une file d’attente de messages.

Pour obtenir des tutoriels, des exemples, des guides de démarrage rapide et d’autres documents, visitez :

• Pour plus d’informations, consultez la bibliothèque de client Stockage File d’attente Azure pour JavaScript.
• Pour d’autres exemples d’applications Stockage File d’attente Azure, consultez Exemples de bibliothèques de client Stockage File d’attente Azure pour JavaScript.