Používání úložiště Queue z C++

• .NET
• Java
• Python
• Node.js
• C++
• Ruby
• PHP

Tip

Vyzkoušení Microsoft Azure Storage Exploreru

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.

Přehled

V tomto průvodci se dozvíte, jak provádět běžné scénáře pomocí služby Azure Queue Storage. Ukázky jsou napsané v jazyce C++ a používají klientskou knihovnu Azure Storage pro jazyk C++. Mezi popsané scénáře patří vkládání, náhledování, získávání a odstraňování zpráv ve frontě a také vytváření a odstraňování front.

Poznámka

Tato příručka je určená pro klientskou knihovnu Azure Storage pro C++ verze 1.0.0 a novější. Doporučená verze je klientská knihovna Azure Storage verze 2.2.0, která je k dispozici prostřednictvím NuGetu nebo GitHubu.

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, která se má zpracovat asynchronně.

Koncepty služby Fronta

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

• Úč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 účtu ú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 označující, že platnost zprávy nevyprší. Pokud je tento parametr vynechán, výchozí hodnota time-to-live je sedm dní.

• Formát adresy URL: Fronty lze adresovat 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 nechcete v tuto chvíli 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 místní vývoj služby Azure Storage.

Vytvoření aplikace C++

V této příručce použijete funkce úložiště, které lze spustit v aplikaci C++.

Abyste to mohli udělat, budete muset nainstalovat klientskou knihovnu Azure Storage pro C++ a ve svém předplatném Azure vytvořit účet Azure Storage.

Pokud chcete nainstalovat klientskou knihovnu Azure Storage pro C++, můžete použít následující metody:

• Linux: Postupujte podle pokynů uvedených v klientské knihovně Azure Storage pro C++ README: Začínáme na stránce Linuxu.
• Windows: Ve Windows použijte jako správce závislostí vcpkg . Postupujte podle pokynů v rychlém startu a inicializujete vcpkg. Potom knihovnu nainstalujte pomocí následujícího příkazu:

.\vcpkg.exe install azure-storage-cpp

Průvodce sestavením zdrojového kódu a exportem do NuGetu najdete v souboru README .

Konfigurace aplikace pro přístup ke službě Queue Storage

Na začátek souboru C++ přidejte následující příkazy include, kde chcete používat rozhraní API služby Azure Storage pro přístup k frontám:

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

Nastavení připojovacího řetězce služby Azure Storage

Klient Služby Azure Storage používá připojovací řetězec úložiště k ukládání koncových bodů a přihlašovacích údajů pro přístup ke službám správy dat. 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 vašeho účtu úložiště a přístupového klíče pro účet úložiště uvedeného v Azure Portal pro AccountName hodnoty aAccountKey. Informace o účtech úložiště a přístupových klíčích najdete v tématu Informace o účtech Azure Storage. Tento příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce:

// 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 testování aplikace v místním počítači s Windows můžete použít emulátor úložiště Azurite. Azurite je nástroj, který simuluje Azure Blob Storage a Queue Storage na místním vývojovém počítači. 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ě:

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

Pokud chcete spustit Azurite, přečtěte si téma Použití emulátoru Azurite pro místní vývoj služby Azure Storage.

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

Načtení připojovacího řetězce

Třídu můžete použít k reprezentaci cloud_storage_account informací o účtu úložiště. Pokud chcete načíst informace o účtu úložiště z připojovacího řetězce úložiště, můžete použít metodu parse .

// 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í fronty

Objekt cloud_queue_client umožňuje získat referenční objekty pro fronty. Následující kód vytvoří cloud_queue_client objekt.

// 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í objektu cloud_queue_client získáte odkaz na frontu, kterou chcete použít. Pokud fronta neexistuje, můžete ji vytvořit.

// 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 fronty

Pokud chcete vložit zprávu do existující fronty, nejprve vytvořte novou cloud_queue_message. Dále zavolejte metodu add_message . Objekt cloud_queue_message lze vytvořit buď z řetězce (ve formátu UTF-8), nebo z pole bajtů. Tady je kód, který vytvoří frontu (pokud neexistuje) a vloží zprávu 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: Náhled na další zprávu

Voláním metody můžete zobrazit zprávu před frontou, aniž byste ji z fronty odebrali peek_message .

// 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ě

Podle potřeby můžete změnit obsah zprávy přímo ve frontě. Pokud zpráva představuje pracovní úlohu, mohli byste tuto funkci použít k aktualizaci stavu pracovních úloh. Následující kód aktualizuje zprávy ve frontě o nový obsah a prodlouží časový limit viditelnosti na 60 sekund. 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. Tuto techniku můžete použít ke sledování vícekrokových pracovních postupů u zpráv fronty, aniž byste museli začít znovu od začátku, pokud se krok zpracování nezdaří kvůli selhání hardwaru nebo softwaru. 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. Je to ochrana proti tomu, aby zpráva při každém pokusu o zpracování nevyvolala chyby aplikace.

// 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: Zrušení zařazení další zprávy

Kód ve dvou krocích odřadí zprávu z fronty. Když zavoláte get_message, zobrazí se další zpráva ve frontě. Zpráva vrácená z get_message se stane neviditelnou pro jakýkoli jiný kód, který čte zprávy z této fronty. Pokud chcete dokončit odebrání zprávy z fronty, musíte také volat 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. Váš kód volá delete_message hned po zpracování zprávy.

// 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 fronty

Načítání zpráv z fronty si můžete přizpůsobit dvěma způsoby. Za prvé si můžete načíst dávku zpráv (až 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. Následující příklad kódu používá metodu get_messages k získání 20 zpráv v jednom volání. Každou zprávu pak zpracuje pomocí smyčky for . Také se pro každou zprávu nastaví časový limit neviditelnosti 5 minut. Všimněte si, že pět minut začíná pro všechny zprávy najednou, takže po uplynutí pěti minut od volání aplikace get_messagesse všechny zprávy, které nebyly odstraněny, znovu zobrazí.

// 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 fronty

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě. Metoda download_attributes vrátí vlastnosti fronty včetně počtu zpráv. Metoda approximate_message_count získá přibližný počet zpráv ve frontě.

// 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í fronty

Pokud chcete odstranit frontu a všechny zprávy v ní obsažené, zavolejte metodu delete_queue_if_exists objektu 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"));

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

Další kroky

Teď, když jste se seznámili se základy služby Queue Storage, použijte tyto odkazy a získejte další informace o službě Azure Storage.

• Jak používat službu Blob Storage z C++
• Jak používat Table Storage z C++
• Výpis prostředků Azure Storage v C++
• Referenční informace ke klientské knihovně Azure Storage pro C++
• Dokumentace ke službě Azure Storage