Sdílet prostřednictvím

Jak používat Službu Azure Queue Storage z Node.js

  • Článek

Přehled

V této příručce se dozvíte, jak provádět běžné scénáře s využitím Služby Azure Queue Storage. Ukázky jsou napsané pomocí rozhraní API Node.js. Popsané scénáře zahrnují vkládání, náhledy, získávání a odstraňování zpráv fronty. Naučte se také vytvářet a odstraňovat fronty.

Co je Queue Storage?

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke které můžete získat přístup z jakéhokoli místa na světě prostřednictvím ověřených volání s využitím protokolu HTTP nebo HTTPS. Zpráva s jednou frontou může mít velikost až 64 kB a jedna fronta můžete obsahovat miliony zpráv, až do dosažení celkové kapacity účtu úložiště. Queue Storage se často používá k vytvoření backlogu práce pro asynchronní zpracování.

Koncepty služby Fronta

Služba Azure Queue obsahuje následující komponenty:

Komponenty služby Azure Queue

  • Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště. Další informace o účtech úložiště najdete v tématu Přehled účtů úložiště.

  • Fronta: Fronta obsahuje sadu zpráv. Všechny zprávy musí být ve frontě. Upozorňujeme, že název fronty musí být psaný malými písmeny. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.

  • Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní. Pro verzi 2017-07-29 nebo novější může být maximální hodnota Time to Live libovolné kladné číslo nebo -1, což znamená, že platnost zprávy nevyprší. Pokud tento parametr vynecháte, výchozí hodnota TTL (Time to Live) je sedm dnů.

  • Formát adresy URL: Fronty jsou adresovatelné pomocí následujícího formátu adresy URL: http://<storage account>.queue.core.windows.net/<queue>

    Následující adresa URL odkazuje na frontu v diagramu:

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

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je použít Azure Portal. Další informace najdete v tématu Vytvoření účtu úložiště.

Účet úložiště Azure můžete vytvořit také pomocí prostředí Azure PowerShell, rozhraní příkazového řádku Azure nebo pomocí poskytovatele prostředků služby Azure Storage pro .NET.

Pokud v tuto chvíli nechcete vytvořit účet úložiště v Azure, můžete také použít emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí. Další informace najdete v tématu Použití emulátoru Azurite pro vývoj v místním úložišti Azure Storage.

Vytvoření aplikace Node.js

Pokud chcete vytvořit prázdnou aplikaci Node.js, přečtěte si téma Vytvoření Node.js webové aplikace v Azure App Service, sestavení a nasazení Node.js aplikace do Azure Cloud Services pomocí PowerShellu nebo editoru Visual Studio Code.

Konfigurace aplikace pro přístup k úložišti

Klientská knihovna Azure Storage pro JavaScript obsahuje sadu praktických knihoven, které komunikují se službami REST úložiště.

Získání balíčku pomocí správce balíčků node (npm)

  1. Použijte rozhraní příkazového řádku, jako je PowerShell (Windows), Terminál (Mac) nebo Bash (Unix), a přejděte do složky, ve které jste vytvořili ukázkovou aplikaci.

  2. Do příkazového okna zadejte npm install @azure/storage-queue .

  3. Ověřte, že node_modules byla vytvořena složka. V této složce najdete @azure/storage-queue balíček, který obsahuje klientskou knihovnu, kterou potřebujete pro přístup k úložišti.

Import balíčku

Pomocí editoru kódu přidejte následující kód na začátek souboru JavaScriptu, kde chcete používat fronty.

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

Jak vytvořit frontu

Následující kód získá hodnotu proměnné prostředí s názvem AZURE_STORAGE_CONNECTION_STRING a použije ji k vytvoření objektu QueueServiceClient . Tento objekt se pak použije k vytvoření objektu QueueClient , který vám umožní pracovat s konkrétní frontou.

// 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();

Pokud fronta již existuje, vyvolá se výjimka.

Jak naformátovat zprávu

Typ zprávy je řetězec. Všechny zprávy jsou považovány za řetězce. Pokud potřebujete odeslat jiný datový typ, musíte při odesílání zprávy serializovat tento datový typ do řetězce a deserializovat formát řetězce při čtení zprávy.

Pokud chcete převést JSON do formátu řetězce a znovu v Node.js, použijte následující pomocné funkce:

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

Jak vložit zprávu do fronty

Pokud chcete přidat zprávu do fronty, zavolejte metodu sendMessage .

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

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

Jak se podívat na další zprávu

Voláním metody můžete zobrazit náhled na zprávy ve frontě, aniž byste je z fronty odebrali peekMessages .

Ve výchozím nastavení peekMessages se zobrazí náhled jedné zprávy. Následující příklad zobrazí náhled prvních pěti zpráv ve frontě. Pokud je viditelných méně než pět zpráv, vrátí se pouze viditelné zprávy.

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

Volání peekMessages , když ve frontě nejsou žádné zprávy, nevrátí chybu. Nevrátí se však žádné zprávy.

Jak změnit obsah zprávy ve frontě

Následující příklad aktualizuje text zprávy.

Změňte obsah zprávy místně ve frontě voláním updateMessagemetody .

// 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"
);

Postup vyřazení zprávy z fronty

Vyřazení zprávy z fronty je dvoufázový proces:

  1. Získejte zprávu.

  2. Odstraňte zprávu.

Následující příklad získá zprávu a pak ji odstraní.

Pokud chcete získat zprávu, zavolejte metodu receiveMessages . Díky tomuto volání budou zprávy ve frontě neviditelné, takže je žádní jiní klienti nebudou moct zpracovat. Jakmile aplikace zpracuje zprávu, zavolejte deleteMessage ji a odstraňte ji z fronty.

// 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);

Ve výchozím nastavení je zpráva skrytá pouze po dobu 30 sekund. Po 30 sekundách se zobrazí ostatním klientům. Jinou hodnotu můžete zadat nastavením options.visibilityTimeout při volání receiveMessagesmetody .

Volání receiveMessages , když ve frontě nejsou žádné zprávy, nevrátí chybu. Nebudou však vráceny žádné zprávy.

Další možnosti pro vyřazení zpráv z fronty

Načítání zpráv z fronty můžete přizpůsobit dvěma způsoby:

Následující příklad používá metodu receiveMessages k získání pěti zpráv v jednom volání. Každou zprávu pak zpracuje pomocí smyčky for . Nastaví také časový limit neviditelnosti na pět minut pro všechny zprávy vrácené touto metodou.

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

Jak získat délku fronty

Metoda getProperties vrátí metadata o frontě, včetně přibližného počtu zpráv čekajících ve frontě.

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

Jak vypsat fronty

Pokud chcete načíst seznam front, zavolejte .QueueServiceClient.listQueues Pokud chcete načíst seznam filtrovaný podle konkrétní předpony, nastavte ve volání metody options.prefix .listQueues

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

Odstranění fronty

Chcete-li odstranit frontu a všechny zprávy v ní obsažené, zavolejte metodu DeleteQueueQueueClient pro objekt .

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

Pokud chcete vymazat všechny zprávy z fronty, aniž byste ji odstranili, zavolejte .ClearMessages

Tip

Projděte si úložiště s ukázkami kódu pro Azure Storage

Snadno použitelné a úplné ukázky kódu pro Azure Storage, které si můžete stáhnout a použít, jsou shrnuté v seznamu ukázky pro Azure Storage.

Další kroky

Teď, když jste se seznámili se základy služby Queue Storage, použijte tyto odkazy a seznamte se se složitějšími úlohami úložiště.