Queue Storage gebruiken met C++

  • Artikel

Tip

Microsoft Azure Storage Explorer proberen

Microsoft Azure Storage Explorer is een gratis, zelfstandige app van Microsoft waarmee u visueel met Azure Storage-gegevens kunt werken in Windows, macOS en Linux.

Overzicht

Deze handleiding laat zien hoe u algemene scenario's uitvoert met behulp van de Azure Queue Storage-service. De voorbeelden zijn geschreven in C++ en maken gebruik van de Azure Storage-clientbibliotheek voor C++. De scenario's die worden behandeld, omvatten het invoegen, bekijken, ophalen en verwijderen van wachtrijberichten, evenals het maken en verwijderen van wachtrijen.

Notitie

Deze handleiding is gericht op de Azure Storage-clientbibliotheek voor C++ v1.0.0 en hoger. De aanbevolen versie is Azure Storage-clientbibliotheek v2.2.0, die beschikbaar is via NuGet of GitHub.

Wat is Queue Storage?

Azure Queue Storage is een service voor de opslag van grote aantallen berichten die via HTTP of HTTPS overal vandaan kunnen worden opgevraagd met geverifieerde aanroepen. Een enkel wachtrijbericht mag maximaal 64 KB groot zijn en een wachtrij kan miljoenen berichten bevatten, tot de totale capaciteitslimiet van een opslagaccount. Queue Storage wordt vaak gebruikt om een achterstand van werk te maken om asynchroon te verwerken.

Concepten van Queue-service

De Azure Queue-service bevat de volgende onderdelen:

Onderdelen van de Azure Queue-service

  • Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie Overzicht van opslagaccount voor meer informatie over opslagaccounts.

  • Wachtrij: Een wachtrij bevat een set berichten. Alle berichten moeten zich in een wachtrij bevinden. De naam van een wachtrij mag alleen kleine letters bevatten. Zie Naming Queues and Metadata (Wachtrijen en metagegevens een naam geven) voor informatie over de naamgeving van wachtrijen.

  • Bericht: Een bericht in een willekeurige indeling, van maximaal 64 KB. Een bericht kan maximaal 7 dagen in de wachtrij blijven staan. Voor versie 29-07-2017 of hoger mag de maximale time-to-live elk positief getal zijn. Of -1 om aan te geven dat het bericht niet verloopt. Als deze parameter wordt weggelaten, is de standaard time-to-live zeven dagen.

  • URL-indeling: Wachtrijen kunnen worden adresseerbaar met de volgende URL-indeling: http://<storage account>.queue.core.windows.net/<queue>

    Met de volgende URL wordt een wachtrij in het diagram opgevraagd:

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

Een Azure-opslagaccount maken

De eenvoudigste manier om uw eerste Azure-opslagaccount te maken, is met behulp van de Azure Portal. Zie Een opslagaccount maken voor meer informatie.

U kunt ook een Azure-opslagaccount maken met behulp van Azure PowerShell, Azure CLI of de Azure Storage Resource Provider voor .NET.

Als u op dit moment liever geen opslagaccount in Azure maakt, kunt u de Azurite-opslagemulator ook gebruiken om uw code in een lokale omgeving uit te voeren en te testen. Zie Use the Azurite emulator for local Azure Storage development (De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling) voor meer informatie.

Een C++-toepassing maken

In deze handleiding gebruikt u opslagfuncties die kunnen worden uitgevoerd in een C++-toepassing.

Hiervoor moet u de Azure Storage-clientbibliotheek voor C++ installeren en een Azure Storage-account maken in uw Azure-abonnement.

Als u de Azure Storage-clientbibliotheek voor C++ wilt installeren, kunt u de volgende methoden gebruiken:

.\vcpkg.exe install azure-storage-cpp

U vindt een handleiding voor het bouwen van de broncode en het exporteren naar NuGet in het README-bestand .

Uw toepassing configureren voor toegang tot Queue Storage

Voeg de volgende include-instructies toe aan het begin van het C++-bestand waar u de Azure Storage-API's wilt gebruiken voor toegang tot wachtrijen:

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

Een Azure-opslagverbindingstekenreeks instellen

Een Azure Storage-client gebruikt een opslag-connection string om eindpunten en referenties op te slaan voor toegang tot gegevensbeheerservices. Wanneer u uitvoert in een clienttoepassing, moet u de opslag-connection string opgeven in de volgende indeling, met behulp van de naam van uw opslagaccount en de opslagtoegangssleutel voor het opslagaccount dat wordt vermeld in de Azure Portal voor de AccountName waarden enAccountKey. Zie Over Azure Storage-accounts voor meer informatie over opslagaccounts en toegangssleutels. In dit voorbeeld ziet u hoe u een statisch veld kunt declareren voor het opslaan van de verbindingstekenreeks:

// 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"));

Als u uw toepassing op uw lokale Windows-computer wilt testen, kunt u de Azurite-opslagemulator gebruiken. Azurite is een hulpprogramma waarmee Azure Blob Storage en Queue Storage op uw lokale ontwikkelcomputer worden gesimuleerd. In het volgende voorbeeld ziet u hoe u een statisch veld kunt declareren voor het opslaan van de verbindingstekenreeks naar uw lokale opslagemulator:

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

Zie Use the Azurite emulator for local Azure Storage development (De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling) om Azurite te starten.

In de volgende voorbeelden wordt ervan uitgegaan dat u een van deze twee methoden hebt gebruikt om de opslagverbindingstekenreeks op te halen.

De verbindingsreeks ophalen

U kunt de klasse cloud_storage_account gebruiken als representatie van uw opslagaccountgegevens. Als u de gegevens van uw opslagaccount wilt ophalen uit de opslag connection string, kunt u de parse methode gebruiken.

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

Procedure: Een wachtrij maken

Met een cloud_queue_client -object kunt u referentieobjecten voor wachtrijen ophalen. Met de volgende code wordt een cloud_queue_client -object gemaakt.

// 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();

Gebruik het cloud_queue_client -object om een verwijzing op te halen naar de wachtrij die u wilt gebruiken. U kunt de wachtrij maken als deze niet bestaat.

// 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();

Procedure: Een bericht invoegen in een wachtrij

Als u een bericht wilt invoegen in een bestaande wachtrij, maakt u eerst een nieuwe cloud_queue_message. Roep vervolgens de methode aan add_message . Een cloud_queue_message kan worden gemaakt op basis van een tekenreeks (in UTF-8-indeling) of een bytematrix. Hier volgt code waarmee een wachtrij wordt gemaakt (als deze nog niet bestaat) en het bericht Hello, Worldwordt ingevoegd:

// 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);

Procedure: bekijk het volgende bericht

U kunt het bericht bekijken aan de voorzijde van een wachtrij zonder het uit de wachtrij te verwijderen door de methode aan te peek_message roepen.

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

Procedure: de inhoud van een bericht in de wachtrij wijzigen

U kunt de inhoud van een bericht in de wachtrij wijzigen. Als het bericht een werktaak vertegenwoordigt, kunt u deze functie gebruiken om de status van de werktaak bij te werken. Met de volgende code wordt het bericht in de wachtrij bijgewerkt met nieuwe inhoud en wordt de time-out voor de zichtbaarheid met 60 seconden verlengd. Hiermee wordt de status van de werkitems die aan het bericht zijn gekoppeld, opgeslagen en krijgt de client een extra minuut om aan het bericht te blijven werken. U kunt deze techniek gebruiken om werkstromen met meerdere stappen in wachtrijberichten bij te houden, zonder dat u opnieuw hoeft te beginnen als een verwerkingsstap mislukt vanwege hardware- of softwarefouten. Doorgaans houdt u ook het aantal nieuwe pogingen bij en als het bericht meer dan n keer opnieuw is geprobeerd, verwijdert u het. Dit biedt bescherming tegen berichten die een toepassingsfout activeren telkens wanneer ze worden verwerkt.

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

Procedure: Het volgende bericht uit de wachtrij verwijderen

Uw code verwijdert in twee stappen een bericht uit een wachtrij. Wanneer u aanroept get_message, krijgt u het volgende bericht in een wachtrij. Een bericht dat wordt geretourneerd van get_message wordt onzichtbaar voor andere code die berichten uit deze wachtrij leest. Als u het verwijderen van het bericht uit de wachtrij wilt voltooien, moet u ook aanroepen delete_message. Dit proces in twee stappen voor het verwijderen van een bericht zorgt ervoor dat als de code er niet in slaagt een bericht te verwerken vanwege hardware- of softwareproblemen, een ander exemplaar van uw code hetzelfde bericht kan ophalen en het opnieuw kan proberen. Uw code roept aan delete_message zodra het bericht is verwerkt.

// 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);

Procedure: Aanvullende opties gebruiken voor het verwijderen van berichten

Er zijn twee manieren waarop u het ophalen van berichten uit een wachtrij kunt aanpassen. Ten eerste kunt u berichten batchgewijs (maximaal 32) ophalen. Ten tweede kunt u een langere of kortere time-out voor onzichtbaarheid instellen, zodat uw code meer of minder tijd krijgt voor het volledig verwerken van elk bericht. In het volgende codevoorbeeld wordt de get_messages methode gebruikt om 20 berichten in één aanroep op te halen. Vervolgens wordt elk bericht verwerkt met behulp van een for lus. De time-out voor onzichtbaarheid wordt ingesteld op vijf minuten voor elk bericht. Houd er rekening mee dat de vijf minuten voor alle berichten tegelijk worden gestart, dus nadat er vijf minuten zijn verstreken sinds de aanroep naar get_messages, worden alle berichten die niet zijn verwijderd, weer zichtbaar.

// 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;
}

Procedure: De lengte van de wachtrij ophalen

U kunt een schatting ophalen van het aantal berichten in de wachtrij. De download_attributes methode retourneert wachtrijeigenschappen, waaronder het aantal berichten. Met de approximate_message_count methode wordt het geschatte aantal berichten in de wachtrij opgehaald.

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

Procedure: Een wachtrij verwijderen

Als u een wachtrij en alle berichten erin wilt verwijderen, roept u de delete_queue_if_exists methode aan voor het wachtrijobject.

// 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();

Volgende stappen

Nu u de basisbeginselen van Queue Storage hebt geleerd, volgt u deze koppelingen voor meer informatie over Azure Storage.