Používání úložiště Queue z C++How to use Queue Storage from C++

Tip

Vyzkoušení Microsoft Azure Storage ExploreruTry the Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer je bezplatná samostatná aplikace od Microsoftu, která umožňuje vizuálně pracovat s daty Azure Storage ve Windows, macOS a Linuxu.Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

PřehledOverview

Tato příručka vám ukáže, jak provádět běžné scénáře pomocí služby Azure Queue Storage.This guide will show you how to perform common scenarios using the Azure Queue Storage service. Ukázky jsou napsány v jazyce C++ a používají Azure Storage klientské knihovny pro jazyk c++.The samples are written in C++ and use the Azure Storage client library for C++. 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.

Poznámka

Tato příručka cílí na Azure Storage klientské knihovny pro C++ v 1.0.0 a vyšší.This guide targets the Azure Storage client library for C++ v1.0.0 and above. Doporučená verze je Azure Storage Klientská knihovna v 2.2.0, která je dostupná prostřednictvím NuGet nebo GitHubu.The recommended version is Azure Storage client library v2.2.0, which is available via NuGet or GitHub.

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 C++Create a C++ application

V této příručce budete používat funkce úložiště, které se dají spouštět v rámci aplikace v jazyce C++.In this guide, you will use storage features which can be run within a C++ application.

K tomu budete muset nainstalovat Azure Storage klientskou knihovnu pro C++ a vytvořit účet Azure Storage ve vašem předplatném Azure.To do so, you will need to install the Azure Storage client library for C++ and create an Azure Storage account in your Azure subscription.

Chcete-li nainstalovat knihovnu klienta Azure Storage pro jazyk C++, můžete použít následující metody:To install the Azure Storage client library for C++, you can use the following methods:

.\vcpkg.exe install azure-storage-cpp

Můžete najít průvodce pro sestavení zdrojového kódu a exportovat ho do NuGet v souboru Readme .You can find a guide for how to build the source code and export to NuGet in the README file.

Konfigurace aplikace pro přístup k Queue StorageConfigure your application to access Queue Storage

Do horní části souboru C++ přidejte následující příkazy include, u kterých chcete pro přístup k frontám použít rozhraní Azure Storage API:Add the following include statements to the top of the C++ file where you want to use the Azure Storage APIs to access queues:

#include <was/storage_account.h>
#include <was/queue.h>

Nastavení připojovacího řetězce služby Azure StorageSet up an Azure Storage connection string

Klient Azure Storage používá připojovací řetězec úložiště k uložení koncových bodů a přihlašovacích údajů pro přístup ke službám pro správu dat.An Azure Storage client uses a storage connection string to store endpoints and credentials for accessing data management services. Při spuštění v klientské aplikaci musíte zadat připojovací řetězec úložiště v následujícím formátu s použitím názvu účtu úložiště a přístupového klíče úložiště pro účet úložiště, který je uvedený v Azure Portal pro AccountName AccountKey hodnoty a.When running in a client application, you must provide the storage connection string in the following format, using the name of your storage account and the storage access key for the storage account listed in the Azure portal for the AccountName and AccountKey values. Informace o účtech úložiště a přístupových klíčích najdete v tématu informace o Azure Storagech účtech.For information on storage accounts and access keys, see About Azure Storage accounts. Tento příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce:This example shows how you can declare a static field to hold the connection string:

// Define the connection-string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_storage_account_key"));

K otestování aplikace na místním počítači s Windows můžete použít emulátor úložiště Azurite.To test your application in your local Windows computer, you can use the Azurite storage emulator. Azurite je nástroj, který simuluje Azure Blob Storage a Queue Storage na místním vývojovém počítači.Azurite is a utility that simulates Azure Blob Storage and Queue Storage on your local development machine. Následující příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce k místnímu emulátoru úložiště:The following example shows how you can declare a static field to hold the connection string to your local storage emulator:

// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));  

Pokud chcete začít Azurite, přečtěte si téma použití emulátoru Azurite pro vývoj místních Azure Storage.To start Azurite, see Use the Azurite emulator for local Azure Storage development.

V následujících ukázkách se předpokládá, že jste pomocí některé z těchto dvou metod získali připojovací řetězec úložiště.The following samples assume that you have used one of these two methods to get the storage connection string.

Načtení připojovacího řetězceRetrieve your connection string

Třídu můžete použít cloud_storage_account k reprezentaci informací o svém účtu úložiště.You can use the cloud_storage_account class to represent your storage account information. Pokud chcete načíst informace o účtu úložiště z připojovacího řetězce úložiště, můžete použít parse metodu.To retrieve your storage account information from the storage connection string, you can use the parse method.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

Postupy: vytvoření frontyHow to: Create a queue

cloud_queue_clientObjekt umožňuje získat referenční objekty pro fronty.A cloud_queue_client object lets you get reference objects for queues. Následující kód vytvoří cloud_queue_client objekt.The following code creates a cloud_queue_client object.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create a queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

Pomocí cloud_queue_client objektu získáte odkaz na frontu, kterou chcete použít.Use the cloud_queue_client object to get a reference to the queue you want to use. Tuto frontu můžete vytvořit, pokud neexistuje.You can create the queue if it doesn't exist.

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Create the queue if it doesn't already exist.
queue.create_if_not_exists();  

Postupy: vložení zprávy do frontyHow to: Insert a message into a queue

Chcete-li vložit zprávu do existující fronty, vytvořte nejprve novou cloud_queue_message .To insert a message into an existing queue, first create a new cloud_queue_message. Dále zavolejte add_message metodu.Next, call the add_message method. A cloud_queue_message lze vytvořit buď z řetězce (ve formátu UTF-8), nebo pole bajtů.A cloud_queue_message can be created from either a string (in UTF-8 format) or a byte array. Zde je kód, který vytvoří frontu (Pokud neexistuje) a vloží zprávu Hello, World :Here is code which creates a queue (if it doesn't exist) and inserts the message Hello, World:

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Create the queue if it doesn't already exist.
queue.create_if_not_exists();

// Create a message and add it to the queue.
azure::storage::cloud_queue_message message1(U("Hello, World"));
queue.add_message(message1);  

Postupy: prohlížení další zprávyHow to: Peek at the next message

Můžete prohlížet zprávy před frontou, aniž byste je museli odebírat z fronty voláním peek_message metody.You can peek at the message in the front of a queue without removing it from the queue by calling the peek_message method.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Peek at the next message.
azure::storage::cloud_queue_message peeked_message = queue.peek_message();

// Output the message content.
std::wcout << U("Peeked message content: ") << peeked_message.content_as_string() << std::endl;

Postupy: Změna obsahu zprávy ve frontěHow to: Change the contents of a queued message

Podle potřeby můžete změnit obsah zprávy přímo ve frontě.You can change the contents of a message in-place in the queue. Pokud zpráva představuje pracovní úlohu, mohli byste tuto funkci použít k aktualizaci stavu pracovních úloh.If the message represents a work task, you could use this feature to update the status of the work task. Následující kód aktualizuje zprávy ve frontě o nový obsah a prodlouží časový limit viditelnosti na 60 sekund.The following code updates the queue message with new contents, and sets the visibility timeout to extend another 60 seconds. Uloží se tím stav práce spojený se zprávou a klient získá další minutu, aby mohl pokračovat ve zpracování zprávy.This saves the state of work associated with the message, and gives the client another minute to continue working on the message. Tento postup můžete použít ke sledování pracovních postupů ve frontě, aniž byste museli začít znovu od začátku, pokud krok zpracování selže kvůli selhání hardwaru nebo softwaru.You could use this technique to track multistep workflows on queue messages, without having to start over from the beginning if a processing step fails due to hardware or software failure. Obvykle byste udržovali také hodnotu počtu opakování, a pokud by se pokus o zpracování zprávy opakoval více než nkrát, odstranili byste ji.Typically, you would keep a retry count as well, and if the message is retried more than n times, you would delete it. Je to ochrana proti tomu, aby zpráva při každém pokusu o zpracování nevyvolala chyby aplikace.This protects against a message that triggers an application error each time it is processed.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Get the message from the queue and update the message contents.
// The visibility timeout "0" means make it visible immediately.
// The visibility timeout "60" means the client can get another minute to continue
// working on the message.
azure::storage::cloud_queue_message changed_message = queue.get_message();

changed_message.set_content(U("Changed message"));
queue.update_message(changed_message, std::chrono::seconds(60), true);

// Output the message content.
std::wcout << U("Changed message content: ") << changed_message.content_as_string() << std::endl;  

Postupy: vyřazení další zprávy z frontyHow to: Dequeue the next message

Váš kód vyřadí zprávu z fronty ve dvou krocích.Your code dequeues a message from a queue in two steps. Když zavoláte get_message , dostanete další zprávu ve frontě.When you call get_message, you get the next message in a queue. Zpráva vrácená z get_message se bude neviditelná pro jakýkoliv jiný kód, který čte zprávy z této fronty.A message returned from get_message becomes invisible to any other code reading messages from this queue. Chcete-li dokončit odebrání zprávy z fronty, je také nutné zavolat delete_message .To finish removing the message from the queue, you must also call delete_message. Tento dvoukrokový proces odebrání zprávy zaručuje, aby v případě, že se vašemu kódu nepodaří zprávu zpracovat z důvodu selhání hardwaru nebo softwaru, mohla stejnou zprávu získat jiná instance vašeho kódu a bylo možné to zkusit znovu.This two-step process of removing a message assures that if your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. Váš kód volá delete_message hned po zpracování zprávy.Your code calls delete_message right after the message has been processed.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Get the next message.
azure::storage::cloud_queue_message dequeued_message = queue.get_message();
std::wcout << U("Dequeued message: ") << dequeued_message.content_as_string() << std::endl;

// Delete the message.
queue.delete_message(dequeued_message);

Postupy: použití dalších možností pro vyřazení zpráv z frontyHow to: Use additional options for dequeuing messages

Načítání zpráv z fronty si můžete přizpůsobit dvěma způsoby.There are two ways you can customize message retrieval from a queue. Za prvé si můžete načíst dávku zpráv (až 32).First, you can get a batch of messages (up to 32). Za druhé si můžete nastavit delší nebo kratší časový limit neviditelnosti, aby měl váš kód více nebo méně času na úplné zpracování jednotlivých zpráv.Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message. Následující příklad kódu používá get_messages metodu k získání 20 zpráv v jednom volání.The following code example uses the get_messages method to get 20 messages in one call. Pak každou zprávu zpracuje pomocí for smyčky.Then it processes each message using a for loop. Také se pro každou zprávu nastaví časový limit neviditelnosti 5 minut.It also sets the invisibility timeout to five minutes for each message. Všimněte si, že pět minut začíná u všech zpráv současně, takže po pěti minutách od jejich volání se get_messages všechny zprávy, které nebyly odstraněny, opět zobrazí.Note that the five minutes starts for all messages at the same time, so after five minutes have passed since the call to get_messages, any messages which have not been deleted will become visible again.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Dequeue some queue messages (maximum 32 at a time) and set their visibility timeout to
// 5 minutes (300 seconds).
azure::storage::queue_request_options options;
azure::storage::operation_context context;

// Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
std::vector<azure::storage::cloud_queue_message> messages = queue.get_messages(20, std::chrono::seconds(300), options, context);

for (auto it = messages.cbegin(); it != messages.cend(); ++it)
{
    // Display the contents of the message.
    std::wcout << U("Get: ") << it->content_as_string() << std::endl;
}

Postupy: získání délky frontyHow to: Get the queue length

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě.You can get an estimate of the number of messages in a queue. download_attributesMetoda vrátí vlastnosti fronty včetně počtu zpráv.The download_attributes method returns queue properties including the message count. approximate_message_countMetoda získá přibližný počet zpráv ve frontě.The approximate_message_count method gets the approximate number of messages in the queue.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Fetch the queue attributes.
queue.download_attributes();

// Retrieve the cached approximate message count.
int cachedMessageCount = queue.approximate_message_count();

// Display number of messages.
std::wcout << U("Number of messages in queue: ") << cachedMessageCount << std::endl;  

Postupy: odstranění frontyHow to: Delete a queue

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

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// If the queue exists and delete it.
queue.delete_queue_if_exists();  

Další krokyNext steps

Teď, když jste se naučili základy Queue Storage, přečtěte si následující odkazy, kde najdete další informace o Azure Storage.Now that you've learned the basics of Queue Storage, follow these links to learn more about Azure Storage.