Použití služby Azure Queue k vytváření a odstraňování front z Node. jsUse Azure Queue Service to create and delete queues from Node.js

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.

PřehledOverview

V této příručce se dozvíte, jak provádět běžné scénáře pomocí Služba front Microsoft Azure.This guide shows you how to perform common scenarios using the Microsoft Azure Queue service. Ukázky jsou zapisovány 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 a vytváření a odstraňování front.The scenarios covered include inserting, peeking, getting, and deleting queue messages, as well as creating and deleting 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

  • 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/images-to-download

  • Úč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ě] [.. /articles/storage/common/storage-account-overview.md].For more information about storage accounts, see [Storage account overview][../articles/storage/common/storage-account-overview.md].

  • 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.

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í webu 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 vytvořit účet úložiště v tomto okamžiku, můžete použít taky emulátor úložiště Azure 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 Azure storage emulator to run and test your code in a local environment. Další informace najdete v článku Použití emulátoru úložiště Azure pro vývoj a testování.For more information, see Use the Azure Storage Emulator for Development and Testing.

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

Vytvořte prázdnou aplikaci Node. js.Create a blank Node.js application. Pokyny k vytvoření aplikace Node. js najdete v tématu Vytvoření webové aplikace Node. js v Azure App Service, sestavení a nasazení aplikace Node. js do cloudové služby Azure pomocí Windows PowerShellu nebo Visual Studio Code.For instructions creating a Node.js application, see Create a Node.js web app in Azure App Service, Build and deploy a Node.js application to an Azure Cloud Service using Windows PowerShell, or Visual Studio Code.

Konfigurace aplikace pro přístup k úložištiConfigure Your Application to Access Storage

Pokud chcete používat službu Azure Storage, potřebujete sadu Azure Storage SDK pro Node. js, která zahrnuje sadu praktických knihoven, které komunikují se službou REST (Storage).To use Azure storage, you need the Azure Storage SDK for Node.js, which 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, například PowerShell (Windows,) Terminal (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.

  2. Do příkazového okna zadejte npm install azure-storage.Type npm install azure-storage in the command window. Výstup příkazu je podobný následujícímu příkladu.Output from the command is similar to the following example.

    azure-storage@0.5.0 node_modules\azure-storage
    +-- extend@1.2.1
    +-- xmlbuilder@0.4.3
    +-- mime@1.2.11
    +-- node-uuid@1.4.3
    +-- validator@3.22.2
    +-- underscore@1.4.4
    +-- readable-stream@1.0.33 (string_decoder@0.10.31, isarray@0.0.1, inherits@2.0.1, core-util-is@1.0.1)
    +-- xml2js@0.2.7 (sax@0.5.2)
    +-- request@2.57.0 (caseless@0.10.0, aws-sign2@0.5.0, forever-agent@0.6.1, stringstream@0.0.4, oauth-sign@0.8.0, tunnel-agent@0.4.1, isstream@0.1.2, json-stringify-safe@5.0.1, bl@0.9.4, combined-stream@1.0.5, qs@3.1.0, mime-types@2.0.14, form-data@0.2.0, http-signature@0.11.0, tough-cookie@2.0.0, hawk@2.3.1, har-validator@1.8.0)
    
  3. Můžete ručně spustit příkaz ls a ověřit tak, že se vytvořila složka modulů uzlů_ .You can manually run the ls command to verify that a node_modules folder was created. Uvnitř této složky najdete balíček azure-storage obsahující knihovny, které potřebujete pro přístup k úložišti.Inside that folder you will find the azure-storage package, which contains the libraries you need to access storage.

Import balíčkuImport the package

Pomocí poznámkového bloku nebo jiného textového editoru přidejte do horní části souboru Server. js aplikace, ve které chcete úložiště použít, následující:Using Notepad or another text editor, add the following to the top the server.js file of the application where you intend to use storage:

var azure = require('azure-storage');

Nastavení Azure Storageho připojeníSetup an Azure Storage Connection

Modul Azure_přečte proměnné prostředí účet úložiště_Azure a přístupový klíč Azure_Storage_nebo_připojení__kAzureStorage._ ŘETĚZEC pro informace požadované pro připojení k účtu úložiště Azure.The azure module will read the environment variables AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY, or AZURE_STORAGE_CONNECTION_STRING for information required to connect to your Azure storage account. Pokud tyto proměnné prostředí nejsou nastaveny, při volání createQueueServiceje nutné zadat informace o účtu.If these environment variables are not set, you must specify the account information when calling createQueueService.

Jak: Vytvoření frontyHow To: Create a Queue

Následující kód vytvoří objekt QueueService , který vám umožní pracovat s frontami.The following code creates a QueueService object, which enables you to work with queues.

var queueSvc = azure.createQueueService();

Použijte metodu createQueueIfNotExists , která vrátí zadanou frontu, pokud již existuje, nebo vytvoří novou frontu se zadaným názvem, pokud ještě neexistuje.Use the createQueueIfNotExists method, which returns the specified queue if it already exists or creates a new queue with the specified name if it does not already exist.

queueSvc.createQueueIfNotExists('myqueue', function(error, results, response){
  if(!error){
    // Queue created or exists
  }
});

Pokud je fronta vytvořená, result.created má hodnotu true.If the queue is created, result.created is true. Pokud fronta existuje, result.created je false.If the queue exists, result.created is false.

FiltryFilters

Volitelné operace filtrování lze použít na operace prováděné pomocí QueueService.Optional filtering operations can be applied to operations performed using QueueService. Operace filtrování můžou zahrnovat protokolování, automatické opakování atd. Filtry jsou objekty, které implementují metodu s podpisem:Filtering operations can include logging, automatically retrying, etc. Filters are objects that implement a method with the signature:

function handle (requestOptions, next)

Po provedení předběžného zpracování v možnostech žádosti musí metoda volat "Další" předání zpětného volání s následujícím podpisem:After doing its preprocessing on the request options, the method needs to call "next" passing a callback with the following signature:

function (returnObject, finalCallback, next)

V tomto zpětném volání a po zpracování returnObject (odpověď z požadavku na server) musí zpětné volání vyvolat další, pokud existuje, aby pokračoval v zpracovávání jiných filtrů, nebo jednoduše vyvolat finalCallback, aby se služba ukončila. vyvolání.In this callback, and after processing the returnObject (the response from the request to the server), the callback needs to either invoke next if it exists to continue processing other filters or simply invoke finalCallback otherwise to end up the service invocation.

Sada Azure SDK pro Node.js obsahuje dva filtry, které implementují logiku opakování: ExponentialRetryPolicyFilter a LinearRetryPolicyFilter.Two filters that implement retry logic are included with the Azure SDK for Node.js, ExponentialRetryPolicyFilter and LinearRetryPolicyFilter. Následující vytvoří objekt QueueService , který používá ExponentialRetryPolicyFilter:The following creates a QueueService object that uses the ExponentialRetryPolicyFilter:

var retryOperations = new azure.ExponentialRetryPolicyFilter();
var queueSvc = azure.createQueueService().withFilter(retryOperations);

Jak: Vložení zprávy do frontyHow To: Insert a Message into a Queue

Chcete-li vložit zprávu do fronty, použijte metodu createMessage k vytvoření nové zprávy a přidejte ji do fronty.To insert a message into a queue, use the createMessage method to create a new message and add it to the queue.

queueSvc.createMessage('myqueue', "Hello world!", function(error, results, response){
  if(!error){
    // Message inserted
  }
});

Jak: Prohlížet další zprávuHow To: Peek at the Next Message

Můžete prohlížet zprávu v přední části fronty bez jejího odebrání z fronty voláním metody peekMessages .You can peek at the message in the front of a queue without removing it from the queue by calling the peekMessages method. Ve výchozím nastavení peekMessages prohlédne jednu zprávu.By default, peekMessages peeks at a single message.

queueSvc.peekMessages('myqueue', function(error, results, response){
  if(!error){
    // Message text is in results[0].messageText
  }
});

result Obsahuje zprávu.The result contains the message.

Poznámka

V případě, že ve frontě nejsou žádné zprávy, nevrátí se žádná zpráva, ale nevrátí se žádné zprávy.Using peekMessages when there are no messages in the queue will not return an error, however no messages will be returned.

Jak: Vyřazení další zprávy z frontyHow To: Dequeue the Next Message

Zpracování zprávy je proces se dvěma fázemi:Processing a message is a two-stage process:

  1. Vyřadí zprávu do fronty.Dequeue the message.
  2. Odstraňte zprávu.Delete the message.

Chcete-li vyřadit zprávu dofronty, použijte GetMessages.To dequeue a message, use getMessages. Tím se zprávy ve frontě nezobrazují, takže je nemůžou zpracovat žádní další klienti.This makes the messages invisible in the queue, so no other clients can process them. Jakmile aplikace zpracuje zprávu, zavolá deleteMessage , aby ji odstranila z fronty.Once your application has processed a message, call deleteMessage to delete it from the queue. Následující příklad získá zprávu a pak ji odstraní:The following example gets a message, then deletes it:

queueSvc.getMessages('myqueue', function(error, results, response){
  if(!error){
    // Message text is in results[0].messageText
    var message = results[0];
    queueSvc.deleteMessage('myqueue', message.messageId, message.popReceipt, function(error, response){
      if(!error){
        //message deleted
      }
    });
  }
});

Poznámka

Ve výchozím nastavení je zpráva skrytá jenom po dobu 30 sekund, po jejímž uplynutí se budou zobrazovat ostatním klientům.By default, a message is only hidden for 30 seconds, after which it is visible to other clients. Pomocí options.visibilityTimeout se GetMessages můžete zadat jinou hodnotu.You can specify a different value by using options.visibilityTimeout with getMessages.

Poznámka

Pokud ve frontě nejsou žádné zprávy, nevrátí se k chybě žádná zpráva, ale nebudou se vracet žádné zprávy.Using getMessages when there are no messages in the queue will not return an error, however no messages will be returned.

Jak: Změna obsahu zprávy ve frontěHow To: Change the Contents of a Queued Message

Můžete změnit obsah zprávy na místě ve frontě pomocí updateMessage.You can change the contents of a message in-place in the queue using updateMessage. Následující příklad aktualizuje text zprávy:The following example updates the text of a message:

queueSvc.getMessages('myqueue', function(error, getResults, getResponse){
  if(!error){
    // Got the message
    var message = getResults[0];
    queueSvc.updateMessage('myqueue', message.messageId, message.popReceipt, 10, {messageText: 'new text'}, function(error, updateResults, updateResponse){
      if(!error){
        // Message updated successfully
      }
    });
  }
});

Jak: Další možnosti pro vyřazování zpráv do frontyHow To: Additional 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:

  • options.numOfMessages-Načíst dávku zpráv (až 32.)options.numOfMessages - Retrieve a batch of messages (up to 32.)
  • options.visibilityTimeout– Nastavte delší nebo kratší časový limit pro neviditelnost.options.visibilityTimeout - Set a longer or shorter invisibility timeout.

Následující příklad používá metodu GetMessages k získání 15 zpráv v jednom volání.The following example uses the getMessages method to get 15 messages in one call. Potom zpracuje každou zprávu pomocí smyčky for.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.

queueSvc.getMessages('myqueue', {numOfMessages: 15, visibilityTimeout: 5 * 60}, function(error, results, getResponse){
  if(!error){
    // Messages retrieved
    for(var index in result){
      // text is available in result[index].messageText
      var message = results[index];
      queueSvc.deleteMessage(queueName, message.messageId, message.popReceipt, function(error, deleteResponse){
        if(!error){
          // Message deleted
        }
      });
    }
  }
});

Jak: Získat délku frontyHow To: Get the Queue Length

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

queueSvc.getQueueMetadata('myqueue', function(error, results, response){
  if(!error){
    // Queue length is available in results.approximateMessageCount
  }
});

Jak: Výpis frontHow To: List Queues

Chcete-li načíst seznam front, použijte listQueuesSegmented.To retrieve a list of queues, use listQueuesSegmented. Chcete-li načíst seznam filtrovaný podle konkrétní předpony, použijte listQueuesSegmentedWithPrefix.To retrieve a list filtered by a specific prefix, use listQueuesSegmentedWithPrefix.

queueSvc.listQueuesSegmented(null, function(error, results, response){
  if(!error){
    // results.entries contains the list of queues
  }
});

Pokud nelze vrátit všechny fronty, result.continuationToken lze použít jako první parametr listQueuesSegmented nebo druhý parametr listQueuesSegmentedWithPrefix pro získání dalších výsledků.If all queues cannot be returned, result.continuationToken can be used as the first parameter of listQueuesSegmented or the second parameter of listQueuesSegmentedWithPrefix to retrieve more results.

Jak: Odstranění frontyHow To: Delete a Queue

Pokud chcete odstranit frontu a všechny zprávy, které jsou v ní obsažené, zavolejte metodu deleteQueue u objektu Queue.To delete a queue and all the messages contained in it, call the deleteQueue method on the queue object.

queueSvc.deleteQueue(queueName, function(error, response){
  if(!error){
    // Queue has been deleted
  }
});

Pokud chcete vymazat všechny zprávy z fronty bez jejich odstranění, použijte clearMessages.To clear all messages from a queue without deleting it, use clearMessages.

Postup: Použití sdílených přístupových podpisůHow to: Work with Shared Access Signatures

Sdílené přístupové podpisy (SAS) představují zabezpečený způsob, jak zajistit podrobný přístup k frontám bez zadání názvu nebo klíčů účtu úložiště.Shared Access Signatures (SAS) are a secure way to provide granular access to queues without providing your storage account name or keys. SAS se často používá k zajištění omezeného přístupu k vašim frontám, jako je například umožnění odesílání zpráv do mobilní aplikace.SAS are often used to provide limited access to your queues, such as allowing a mobile app to submit messages.

Důvěryhodná aplikace, jako je cloudová služba, generuje SAS pomocí GenerateSharedAccessSignature QueueServicea poskytuje ji pro nedůvěryhodnou nebo částečně důvěryhodnou aplikaci.A trusted application such as a cloud-based service generates a SAS using the generateSharedAccessSignature of the QueueService, and provides it to an untrusted or semi-trusted application. Například mobilní aplikace.For example, a mobile app. SAS se generuje pomocí zásady, která popisuje počáteční a koncové datum platnosti SAS a také úroveň přístupu udělenou držiteli SAS.The SAS is generated using a policy, which describes the start and end dates during which the SAS is valid, as well as the access level granted to the SAS holder.

Následující příklad vygeneruje nové zásady sdíleného přístupu, které umožní držiteli SAS přidat zprávy do fronty a vyprší 100 minut od okamžiku jejího vytvoření.The following example generates a new shared access policy that will allow the SAS holder to add messages to the queue, and expires 100 minutes after the time it is created.

var startDate = new Date();
var expiryDate = new Date(startDate);
expiryDate.setMinutes(startDate.getMinutes() + 100);
startDate.setMinutes(startDate.getMinutes() - 100);

var sharedAccessPolicy = {
  AccessPolicy: {
    Permissions: azure.QueueUtilities.SharedAccessPermissions.ADD,
    Start: startDate,
    Expiry: expiryDate
  }
};

var queueSAS = queueSvc.generateSharedAccessSignature('myqueue', sharedAccessPolicy);
var host = queueSvc.host;

Všimněte si, že informace o hostiteli musí být k dispozici také v případě, že se vyžaduje, když se držitel SAS pokusí o přístup ke frontě.Note that the host information must be provided also, as it is required when the SAS holder attempts to access the queue.

Klientská aplikace pak pomocí SAS s QueueServiceWithSAS provede operace s frontou.The client application then uses the SAS with QueueServiceWithSAS to perform operations against the queue. Následující příklad se připojí ke frontě a vytvoří zprávu.The following example connects to the queue and creates a message.

var sharedQueueService = azure.createQueueServiceWithSas(host, queueSAS);
sharedQueueService.createMessage('myqueue', 'Hello world from SAS!', function(error, result, response){
  if(!error){
    //message added
  }
});

Vzhledem k tomu, že se SAS vygeneroval s oprávněním přidat přístup, pokud došlo k pokusu o čtení, aktualizaci nebo odstranění zpráv, vrátí se chyba.Since the SAS was generated with add access, if an attempt were made to read, update or delete messages, an error would be returned.

Seznamy řízení přístupuAccess control lists

K nastavení zásad přístupu pro SAS můžete použít také seznam řízení přístupu (ACL).You can also use an Access Control List (ACL) to set the access policy for a SAS. To je užitečné, pokud chcete, aby přístup k frontě umožňovalo více klientů, ale poskytovaly pro každého klienta různé zásady přístupu.This is useful if you wish to allow multiple clients to access the queue, but provide different access policies for each client.

Seznam ACL se implementuje pomocí pole zásad přístupu, z nichž každá zásada má přidružené ID.An ACL is implemented using an array of access policies, with an ID associated with each policy. Následující příklad definuje dvě zásady. jednu pro ' uživatel1 ' a jednu pro ' uživatel2 ':The following example defines two policies; one for 'user1' and one for 'user2':

var sharedAccessPolicy = {
  user1: {
    Permissions: azure.QueueUtilities.SharedAccessPermissions.PROCESS,
    Start: startDate,
    Expiry: expiryDate
  },
  user2: {
    Permissions: azure.QueueUtilities.SharedAccessPermissions.ADD,
    Start: startDate,
    Expiry: expiryDate
  }
};

Následující příklad načte aktuální seznam ACL pro MyQueuea pak přidá nové zásady pomocí setQueueAcl.The following example gets the current ACL for myqueue, then adds the new policies using setQueueAcl. Tento přístup umožňuje:This approach allows:

var extend = require('extend');
queueSvc.getQueueAcl('myqueue', function(error, result, response) {
  if(!error){
    var newSignedIdentifiers = extend(true, result.signedIdentifiers, sharedAccessPolicy);
    queueSvc.setQueueAcl('myqueue', newSignedIdentifiers, function(error, result, response){
      if(!error){
        // ACL set
      }
    });
  }
});

Po nastavení seznamu ACL můžete vytvořit SAS na základě ID zásady.Once the ACL has been set, you can then create a SAS based on the ID for a policy. Následující příklad vytvoří nový SAS pro uživatele user2:The following example creates a new SAS for 'user2':

queueSAS = queueSvc.generateSharedAccessSignature('myqueue', { Id: 'user2' });

Další krokyNext Steps

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

Vytvoření webové aplikace v Node. js v Azure App ServiceCreate a Node.js web app in Azure App Service

Vytvoření a nasazení aplikace Node.js do Azure Cloud ServiceBuild and deploy a Node.js application to an Azure Cloud Service