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

Přehled

Tato příručka vám ukáže, 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í Azure Storage klientskou knihovnu pro jazyk C++. Mezi zahrnuté scénáře patří vkládání, prohlížení, získávání a odstraňování zpráv fronty a také vytváření a odstraňování front.

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ě. Fronta úložiště se často používá k vytvoření nevyřízených položek pro asynchronní zpracování.

Služba front koncepty

Služba front Azure 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í. 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ší. Pokud je tento parametr vynechán, výchozí hodnota TTL (Time to Live) je sedm dní.

• Formát adresy URL: Fronty jsou adresovatelné v následujícím 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 pomocí 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 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í. Další informace najdete v tématu použití emulátoru Azurite pro vývoj místních Azure Storage.

Vytvoření aplikace C++

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

K tomu je potřeba nainstalovat klientskou knihovnu Azure Storage pro C++ a vytvořit účet Azure Storage ve vašem předplatném Azure.

Chcete-li Azure Storage klientskou knihovnu pro jazyk C++, můžete použít následující metody:

• Linux: Postupujte podle pokynů uvedených v souboru README Azure Storage pro soubor README jazyka C++: Začínáme na stránce Linuxu.
• Windows: Na Windows jako správce vcpkg závislostí použijte následující. Postupujte podle rychlého startu a inicializujte vcpkg . Pak pomocí následujícího příkazu nainstalujte knihovnu:

.\vcpkg.exe install azure-storage-cpp

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

Konfigurace aplikace pro přístup k frontě Storage

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

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

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

Klient 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, a to pomocí názvu účtu úložiště a přístupového klíče k úložišti pro účet úložiště uvedený v Azure Portal pro hodnoty a AccountName AccountKey . Informace o účtech úložiště a přístupových klíčích najdete v tématu Informace Azure Storage účtech. 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 otestování aplikace v místním Windows počítače můžete použít emulátor úložiště Azure. Azureite je nástroj, který simuluje azure blob Storage a 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 Azureite, podívejte se na stránku Použití emulátoru Azure pro místní Azure Storage vývoji.

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 cloud_storage_account k reprezentaci informací o účtu úložiště. K načtení informací o účtu úložiště z připojovacího řetězce úložiště můžete použít parse metodu .

// 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í cloud_queue_client objektu získejte 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 add_message metodu . Objekt cloud_queue_message se může vytvořit buď z řetězce (ve formátu UTF-8), nebo z bajtového pole. 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: Prohlížení další zprávy

Můžete se podívat na zprávu v přední části fronty, aniž byste ji odebíraní z fronty voláním peek_message metody .

// 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é pracovní postupy ve zprávách fronty, aniž byste museli začít znovu od začátku, pokud krok zpracování selže z důvodu 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: Vyřadí další zprávu z fronty.

Váš kód ve dvou krocích z fronty zprávu z fronty z fronty zařadí do fronty. Když zavoláte get_message , zobrazí se další zpráva ve frontě. Zpráva vrácená z se get_message 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é zavolat 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 delete_message volá 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 dequeuing zpráv

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á get_messages metodu k získání 20 zpráv v jednom volání. Pak každou zprávu zpracuje pomocí for smyčky . 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í metody se všechny zprávy, které nebyly odstraněny, znovu get_messages 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, které obsahuje, zavolejte delete_queue_if_exists metodu pro objekt fronty.

// 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 naučili základy funkce Queue Storage, použijte tyto odkazy a získejte další informace o Azure Storage.

• Jak používat objekty blob Storage z C++
• Jak používat tabulkové Storage z C++
• Výpis prostředků Azure Storage v C++
• Azure Storage klientská knihovna pro jazyk C++
• Dokumentace ke službě Azure Storage