Jak používat Azure Queue Storage z Node.jsHow to use Azure Queue Storage from Node.js

PřehledOverview

V této příručce se dozvíte, jak provádět běžné scénáře pomocí Azure Queue Storage.This guide shows you how to accomplish common scenarios using Azure Queue Storage. Ukázky se napíší pomocí rozhraní Node.js API.The samples are written using the Node.js API. Mezi zahrnuté scénáře patří vkládání, prohlížení, získávání a odstraňování zpráv fronty.The scenarios covered include inserting, peeking, getting, and deleting queue messages. Také se naučíte vytvářet a odstraňovat fronty.Also learn to create and delete queues.

Co je Queue Storage?What is 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.Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or 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ě.A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account. Fronta úložiště se často používá k vytvoření nevyřízených položek pro asynchronní zpracování.Queue storage is often used to create a backlog of work to process asynchronously.

Služba front konceptyQueue service concepts

Služba front Azure obsahuje následující komponenty:The Azure Queue service contains the following components:

Součásti Azure Služba front

  • Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště.Storage Account: All access to Azure Storage is done through a storage account. Další informace o účtech úložiště najdete v tématu Přehled účtu úložiště.For more information about storage accounts, see Storage account overview.

  • Fronta: Fronta obsahuje sadu zpráv.Queue: A queue contains a set of messages. Všechny zprávy musí být ve frontě.All messages must be in a queue. Upozorňujeme, že název fronty musí být psaný malými písmeny.Note that the queue name must be all lowercase. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.For information on naming queues, see Naming Queues and Metadata.

  • Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB.Message: A message, in any format, of up to 64 KB. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní.The maximum time that a message can remain in the queue is 7 days. V případě verze 2017-07-29 nebo novější může být maximální doba do živého kladného čísla nebo-1, což znamená, že platnost zprávy nevyprší.For version 2017-07-29 or later, the maximum time-to-live can be any positive number, or -1 indicating that the message doesn't expire. Pokud je tento parametr vynechán, výchozí hodnota TTL (Time to Live) je sedm dní.If this parameter is omitted, the default time-to-live is seven days.

  • Formát adresy URL: Fronty jsou adresovatelné v následujícím formátu adresy URL: http:// <storage account> . Queue.Core.Windows.NET/<queue>URL format: Queues are addressable using the following URL format: http://<storage account>.queue.core.windows.net/<queue>

    Následující adresa URL odkazuje na frontu v diagramu:The following URL addresses a queue in the diagram:

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

Vytvoření účtu úložiště AzureCreate an Azure storage account

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je pomocí Azure Portal.The easiest way to create your first Azure storage account is by using the Azure portal. Další informace najdete v tématu Vytvoření účtu úložiště.To learn more, see Create a storage account.

Úč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.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

Pokud nechcete v Azure v tuto chvíli vytvářet účet úložiště, můžete použít taky emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí.If you prefer not to create a storage account in Azure at this time, you can also use the Azurite storage emulator to run and test your code in a local environment. Další informace najdete v tématu použití emulátoru Azurite pro vývoj místních Azure Storage.For more information, see Use the Azurite emulator for local Azure Storage development.

Vytvoření aplikace Node.jsCreate a Node.js application

Pokud chcete vytvořit prázdnou Node.js aplikaci, přečtěte si téma Vytvoření webové aplikace v Node.js v Azure App Service, sestavení a nasazení Node.js aplikace do Azure Cloud Services pomocí PowerShellu nebo Visual Studio Code.To create a blank Node.js application, see Create a Node.js web app in Azure App Service, build and deploy a Node.js application to Azure Cloud Services using PowerShell or Visual Studio Code.

Konfigurace aplikace pro přístup k úložištiConfigure your application to access storage

Klientská knihovna Azure Storage pro jazyk JavaScript obsahuje sadu praktických knihoven, které komunikují se službami REST služby Storage.The Azure Storage client library for JavaScript includes a set of convenience libraries that communicate with the storage REST services.

K získání balíčku použijte Správce balíčků Node (npm).Use Node package manager (npm) to obtain the package

  1. Použijte rozhraní příkazového řádku, jako je PowerShell (Windows), terminál (Mac) nebo bash (UNIX), přejděte do složky, ve které jste vytvořili ukázkovou aplikaci.Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix), navigate to the folder where you created your sample application.
  1. npm install @azure/storage-queueDo příkazového řádku zadejte.Type npm install @azure/storage-queue in the command window.

  2. Ověřte, že se node_modules vytvořila složka.Verify that a node_modules folder was created. 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.Inside that folder you'll find the @azure/storage-queue package, which contains the client library you need to access storage.

Import balíčkuImport the package

Pomocí editoru kódu přidejte následující kód do horní části souboru JavaScriptu, kde máte v úmyslu používat fronty.Using your code editor, add the following to the top the JavaScript file where you intend to use queues.

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

Jak vytvořit frontuHow to create a queue

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í QueueServiceClient objektu.The following code gets the value of an environment variable called AZURE_STORAGE_CONNECTION_STRING and uses it to create a QueueServiceClient object. Tento objekt se pak použije k vytvoření QueueClient objektu, který vám umožní pracovat s konkrétní frontou.This object is then used to create a QueueClient object that allows you to work with a specific queue.

// 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, je vyvolána výjimka.If the queue already exists, an exception is thrown.

Vložení zprávy do frontyHow to insert a message into a queue

Chcete-li přidat zprávu do fronty, zavolejte sendMessage metodu.To add a message to a queue, call the sendMessage method.

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

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

Jak prohlížet další zprávuHow to peek at the next message

Můžete prohlížet zprávy ve frontě bez jejich odebrání z fronty voláním peekMessages metody.You can peek at messages in the queue without removing them from the queue by calling the peekMessages method.

Ve výchozím nastavení se peekMessages v jedné zprávě prohlédne.By default, peekMessages peeks at a single message. Následující příklad si prohlédne prvních pět zpráv ve frontě.The following example peeks at the first five messages in the queue. Pokud jsou viditelné méně než pět zpráv, vrátí se pouze zobrazené zprávy.If fewer than five messages are visible, just the visible messages are returned.

// 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 v případě, že ve frontě nejsou žádné zprávy, nevrátí chybu.Calling peekMessages when there are no messages in the queue won't return an error. Nevrátí se ale žádné zprávy.However, no messages are returned.

Postup změny obsahu zprávy ve frontěHow to change the contents of a queued message

Následující příklad aktualizuje text zprávy.The following example updates the text of a message.

Změňte obsah zprávy na místě ve frontě tak, že zavoláte updateMessage .Change the contents of a message in-place in the queue by calling 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"
);

Jak odřadit zprávu do frontyHow to dequeue a message

Vyřazení zprávy do fronty je proces se dvěma fázemi:Dequeueing a message is a two-stage process:

  1. Získejte zprávu.Get the message.

  2. Odstraňte zprávu.Delete the message.

Následující příklad získá zprávu a pak ji odstraní.The following example gets a message, then deletes it.

Chcete-li získat zprávu, zavolejte receiveMessages metodu.To get a message, call the receiveMessages method. Toto volání zpřístupňuje zprávy ve frontě, takže je nemohou zpracovat žádní další klienti.This call makes the messages invisible in the queue, so no other clients can process them. Jakmile aplikace zpracuje zprávu, zavolejte deleteMessage k jejímu odstranění z fronty.Once your application has processed a message, call deleteMessage to delete it from the queue.

// 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 po dobu 30 sekund skrytá.By default, a message is only hidden for 30 seconds. Po 30 sekundách je uvidí ostatní klienti.After 30 seconds it's visible to other clients. Můžete zadat jinou hodnotu nastavením options.visibilityTimeout při volání receiveMessages .You can specify a different value by setting options.visibilityTimeout when you call receiveMessages.

Volání receiveMessages v případě, že ve frontě nejsou žádné zprávy, nevrátí chybu.Calling receiveMessages when there are no messages in the queue won't return an error. Nebudou ale vráceny žádné zprávy.However, no messages will be returned.

Další možnosti pro vyřazování zpráv do frontyAdditional options for dequeuing messages

Existují dva způsoby, jak lze přizpůsobit načtení zprávy z fronty:There are two ways you can customize message retrieval from a queue:

Následující příklad používá receiveMessages metodu k získání pěti zpráv v jednom volání.The following example uses the receiveMessages method to get five messages in one call. Pak každou zprávu zpracuje pomocí for smyčky.Then it processes each message using a for loop. U všech zpráv vrácených touto metodou nastaví také časový limit neviditelnosti na pět minut.It also sets the invisibility timeout to five minutes for all messages returned by this method.

// 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 frontyHow to get the queue length

getPropertiesMetoda vrátí metadata o frontě, včetně přibližného počtu zpráv čekajících ve frontě.The getProperties method returns metadata about the queue, including the approximate number of messages waiting in the queue.

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

Výpis frontHow to list queues

Chcete-li načíst seznam front, zavolejte QueueServiceClient.listQueues .To retrieve a list of queues, call QueueServiceClient.listQueues. Chcete-li načíst seznam filtrovaný konkrétní předponou, nastavte možnost Options. prefix na listQueues .To retrieve a list filtered by a specific prefix, set options.prefix in your call to listQueues.

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

Postup odstranění frontyHow to delete a queue

Chcete-li odstranit frontu a všechny zprávy, které jsou v něm obsaženy, zavolejte DeleteQueue metodu QueueClient objektu.To delete a queue and all the messages contained in it, call the DeleteQueue method on the QueueClient object.

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

Chcete-li vymazat všechny zprávy z fronty bez jejich odstranění, zavolejte ClearMessages .To clear all messages from a queue without deleting it, call ClearMessages.

Tip

Projděte si úložiště s ukázkami kódu pro Azure StorageCheck out the Azure Storage code samples repository

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.For easy-to-use end-to-end Azure Storage code samples that you can download and run, please check out our list of Azure Storage Samples.

Další krokyNext steps

Teď, když jste se naučili základy Queue Storage, postupujte podle těchto odkazů a získejte další informace o složitějších úlohách úložiště.Now that you've learned the basics of Queue Storage, follow these links to learn about more complex storage tasks.