Condividi tramite

Come usare Archiviazione code di Azure da Node.js

  • Articolo

Panoramica

Questa guida illustra come eseguire scenari comuni usando Archiviazione code di Azure. Gli esempi sono scritti usando l'API Node.js. Gli scenari trattati includono inserimento, visualizzazione, recupero ed eliminazione di messaggi della coda. Informazioni su come creare ed eliminare code.

Che cos'è l'archiviazione code?

Il servizio di archiviazione di accodamento di Azure consente di archiviare grandi quantità di messaggi ai quali è possibile accedere da qualsiasi parte del mondo mediante chiamate autenticate tramite HTTP o HTTPS. La dimensione massima di un singolo messaggio della coda è di 64 KB e una coda può contenere milioni di messaggi, nei limiti della capacità complessiva di un account di archiviazione. L'archiviazione code viene spesso usata per creare un backlog di lavoro da elaborare in modo asincrono.

Concetti del servizio di accodamento

Il servizio di accodamento di Azure contiene i componenti seguenti:

Componenti del servizio code di Azure

  • Account di archiviazione: Tutti gli accessi ad Archiviazione di Azure vengono eseguiti tramite un account di archiviazione. Per altre informazioni sugli account di archiviazione, vedere Panoramica dell'account di archiviazione.

  • Coda: una coda contiene un set di messaggi. Tutti i messaggi devono essere inclusi in una coda. Si noti che il nome della coda deve essere in lettere minuscole. Per altre informazioni, vedere Denominazione di code e metadati.

  • Messaggio: un messaggio, in qualsiasi formato, con dimensioni massime di 64 KB. Il tempo massimo che un messaggio può rimanere nella coda è di 7 giorni. Per la versione 2017-07-29 o successive, la durata massima consentita può essere un numero positivo qualsiasi o -1, a indicare che il messaggio non scade. Se questo parametro viene omesso, la durata predefinita è di sette giorni.

  • Formato URL: Le code sono indirizzabili usando il formato URL seguente: http://<storage account>.queue.core.windows.net/<queue>

    L'URL seguente fa riferimento a una delle code nel diagramma:

    http://myaccount.queue.core.windows.net/incoming-orders

Creare un account di archiviazione di Azure

Il modo più semplice per creare il primo account di archiviazione di Azure consiste nell'usare il portale di Azure. Per altre informazioni, vedere Creare un account di archiviazione.

È anche possibile creare un account di archiviazione di Azure usando Azure PowerShell, l'interfaccia della riga di comando di Azure o il provider di risorse di archiviazione di Azure per .NET.

Se in questo momento non si preferisce creare un account di archiviazione in Azure, è anche possibile usare l'emulatore di archiviazione Azurite per eseguire e testare il codice in un ambiente locale. Per altre informazioni, vedere Usare l'emulatore Azurite per lo sviluppo locale di Archiviazione di Azure.

Creare un'applicazione Node.js

Per creare un'applicazione Node.js vuota, vedere Creare un'app Web Node.js in Servizio app di Azure, compilare e distribuire un'applicazione Node.js in Azure Servizi cloud usando PowerShell o Visual Studio Code.

Configurare l'applicazione per l'accesso all'archiviazione

La libreria client di Archiviazione di Azure per JavaScript include un set di librerie utili che comunicano con i servizi REST di archiviazione.

Usare Gestione pacchetti Node (npm) per ottenere il pacchetto

  1. Usare un'interfaccia della riga di comando, ad esempio PowerShell (Windows), Terminale (Mac) o Bash (Unix), passare alla cartella in cui è stata creata l'applicazione di esempio.

  2. Digitare npm install @azure/storage-queue nella finestra di comando.

  3. Verificare che sia stata creata una node_modules cartella. All'interno di tale cartella si troverà il @azure/storage-queue pacchetto, che contiene la libreria client necessaria per accedere all'archiviazione.

Importare il pacchetto

Usando l'editor di codice, aggiungere quanto segue all'inizio del file JavaScript in cui si intende usare le code.

const { QueueClient, QueueServiceClient } = require("@azure/storage-queue");

Come creare una coda

Il codice seguente ottiene il valore di una variabile di ambiente denominata AZURE_STORAGE_CONNECTION_STRING e la usa per creare un QueueServiceClient oggetto . Questo oggetto viene quindi usato per creare un QueueClient oggetto che consente di usare una coda specifica.

// Retrieve the connection from an environment
// variable called AZURE_STORAGE_CONNECTION_STRING
const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING;

// Create a unique name for the queue
const queueName = "myqueue-" + Date.now().toString();

console.log("Creating queue: ", queueName);

// Instantiate a QueueServiceClient which will be used
// to create a QueueClient and to list all the queues
const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

// Get a QueueClient which will be used
// to create and manipulate a queue
const queueClient = queueServiceClient.getQueueClient(queueName);

// Create the queue
await queueClient.create();

Se la coda esiste già, viene generata un'eccezione.

Come formattare il messaggio

Il tipo di messaggio è una stringa. Tutti i messaggi vengono considerati come stringhe. Se è necessario inviare un tipo di dati diverso, è necessario serializzare tale tipo di dati in una stringa quando si invia il messaggio e si deserializza il formato stringa durante la lettura del messaggio.

Per convertire JSON in un formato stringa e di nuovo in Node.js, usare le funzioni helper seguenti:

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)
}

Come inserire un messaggio in una coda

Per aggiungere un messaggio a una coda, chiamare il sendMessage metodo .

messageText = "Hello, World";
console.log("Adding message to the queue: ", messageText);

// Add a message to the queue
await queueClient.sendMessage(messageText);

Come visualizzare il messaggio successivo

È possibile visualizzare i messaggi nella coda senza rimuoverli dalla coda chiamando il peekMessages metodo .

Per impostazione predefinita, peekMessages visualizza un singolo messaggio. Nell'esempio seguente vengono visualizzati i primi cinque messaggi nella coda. Se sono visibili meno di cinque messaggi, vengono restituiti solo i messaggi visibili.

// 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("Peeked message: ", peekedMessages.peekedMessageItems[i].messageText);
}

La chiamata peekMessages quando non sono presenti messaggi nella coda non restituirà un errore. Tuttavia, non vengono restituiti messaggi.

Come modificare il contenuto di un messaggio in coda

Nell'esempio seguente viene aggiornato il testo di un messaggio.

Modificare il contenuto di un messaggio sul posto nella coda chiamando updateMessage.

// Get the first message in the queue
var receivedMessages = await queueClient.receiveMessages();
const firstMessage = receivedMessages.receivedMessageItems[0];

// Update the received message
await queueClient.updateMessage(
    firstMessage.messageId,
    firstMessage.popReceipt,
    "This message has been updated"
);

Come annullare la coda di un messaggio

La rimozione dalla coda di un messaggio è un processo in due fasi:

  1. Ottenere il messaggio.

  2. Eliminazione del messaggio.

Nell'esempio seguente viene visualizzato un messaggio, quindi viene eliminato.

Per ottenere un messaggio, chiamare il receiveMessages metodo . Questa chiamata rende invisibili i messaggi nella coda, in modo che nessun altro client possa elaborarli. Dopo aver elaborato un messaggio, chiamare deleteMessage per eliminarlo dalla coda.

// Get next message from the queue
receivedMessages = await queueClient.receiveMessages();
var message = receivedMessages.receivedMessageItems[0];

console.log("Dequeuing message: ", message.messageText);

await queueClient.deleteMessage(message.messageId, message.popReceipt);

Per impostazione predefinita, un messaggio è nascosto solo per 30 secondi. Dopo 30 secondi è visibile ad altri client. È possibile specificare un valore diverso impostando options.visibilityTimeout quando si chiama receiveMessages.

La chiamata receiveMessages quando non sono presenti messaggi nella coda non restituirà un errore. Tuttavia, non verrà restituito alcun messaggio.

Opzioni aggiuntive per rimuovere i messaggi dalla coda

È possibile personalizzare il recupero di messaggi da una coda in due modi:

Nell'esempio seguente viene utilizzato il receiveMessages metodo per ottenere cinque messaggi in una chiamata. Ogni messaggio viene poi elaborato con un ciclo for. Per tutti i messaggi restituiti dal metodo, inoltre, il timeout di invisibilità viene impostato su cinque minuti.

// Get up to 5 messages from the queue
const receivedMsgsResp = await queueClient.receiveMessages({ numberOfMessages: 5, visibilityTimeout: 5 * 60 });

for (i = 0; i < receivedMsgsResp.receivedMessageItems.length; i++)
{
    message = receivedMsgsResp.receivedMessageItems[i];
    console.log("Dequeuing message: ", message.messageText);
    await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

Come ottenere la lunghezza della coda

Il getProperties metodo restituisce i metadati relativi alla coda, incluso il numero approssimativo di messaggi in attesa nella coda.

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

Come elencare le code

Per recuperare un elenco di code, chiamare QueueServiceClient.listQueues. Per recuperare un elenco filtrato in base a un prefisso specifico, impostare options.prefix nella chiamata a listQueues.

for await (const item of queueServiceClient.listQueues()) {
  console.log("Queue: ", item.name);
}

Come eliminare una coda

Per eliminare una coda e tutti i messaggi contenuti, chiamare il DeleteQueue metodo sull'oggetto QueueClient .

// Delete the queue
console.log("Deleting queue: ", queueClient.name);
await queueClient.delete();

Per cancellare tutti i messaggi da una coda senza eliminarlo, chiamare ClearMessages.

Suggerimento

Estrarre il repository degli esempi di codice di Archiviazione di Azure

Per esempi di codice end-to-end facile da usare che è possibile scaricare ed eseguire, vedere l'elenco di esempi di Archiviazione di Azure.

Passaggi successivi

Dopo aver appreso le nozioni di base dell'archiviazione code, seguire questi collegamenti per informazioni sulle attività di archiviazione più complesse.