Queue Storage gebruiken vanuit C++
Hint
Probeer de Microsoft Azure Storage Explorer
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
In deze handleiding ziet u hoe u veelvoorkomende scenario's uitvoert met behulp van de Azure Queue Storage-service. De voorbeelden worden geschreven in C++ en gebruiken de Azure Storage-clientbibliotheek voor C++. De scenario's die worden behandeld, zijn het invoegen van, het bekijken van, het ophalen vanen het 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 wachtrijopslag?
Azure Queue Storage is een service voor het opslaan van grote aantallen berichten die overal ter wereld toegankelijk zijn via geverifieerde aanroepen via HTTP of HTTPS. Eén wachtrijbericht kan maximaal 64 kB groot zijn en een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteitslimiet van een opslagaccount. Queue Storage wordt vaak gebruikt om een achterstand van werk te maken om asynchroon te verwerken.
Concepten van wachtrijservice
De Azure Queue-service bevat de volgende onderdelen:
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. De maximale tijd dat een bericht in de wachtrij kan blijven, is 7 dagen. 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 aangesproken met behulp van de volgende URL-indeling: http://
<storage account>.queue.core.windows.net/<queue>Het volgende URL adresseert een wachtrij in het diagram.
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-resourceprovider voor .NET.
Als u op dit moment liever geen opslagaccount in Azure wilt maken, kunt u ook de Emulator van de Azurite-opslag gebruiken om uw code in een lokale omgeving uit te voeren en te testen. Zie De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkelingvoor 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:
- Linux: Volg de instructies gegeven in de Azure Storage-clientbibliotheek voor C++ README: Aan de slag op de Linux-pagina.
-
Windows: In Windows gebruikt u vcpkg als afhankelijkheidsbeheerder. Volg de quickstart om
vcpkgte initialiseren. Voer vervolgens de volgende opdracht uit om de bibliotheek te installeren:
.\vcpkg.exe install azure-storage-cpp
U vindt een handleiding voor het bouwen van de broncode en het exporteren naar NuGet in het bestand README-.
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 maakt gebruik van een opslagverbindingsreeks voor het opslaan van eindpunten en referenties voor toegang tot gegevensbeheerservices. Wanneer u een clienttoepassing uitvoert, moet u de opslag verbindingsreeks in het volgende formaat opgeven, met behulp van de naam van uw opslagaccount en de opslagtoegangssleutel voor het opslagaccount dat wordt vermeld in de Azure-portal voor de waarden AccountName en AccountKey. Zie Over Azure Storage-accountsvoor 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 wilt testen op uw lokale Windows-computer, kunt u de Azurite-opslagemulator gebruiken. Azurite is een hulpprogramma dat Azure Blob Storage en Queue Storage simuleert op uw lokale ontwikkelcomputer. In het volgende voorbeeld ziet u hoe u een statisch veld kunt declareren voor het opslaan van de verbindingsreeks voor uw lokale opslagemulator:
// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));
Zie De Emulator Van Azure Storage gebruiken voor lokale Azure Storage-ontwikkelingom Azurite te starten.
In de volgende voorbeelden wordt ervan uitgegaan dat u een van deze twee methoden hebt gebruikt om de opslagverbindingsreeks 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 opslagverbindingsreeks, kunt u de methode parse 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 te krijgen 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 add_message aan. 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 niet bestaat) en het bericht wordt ingevoegd 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);
Procedure: Gluren naar het volgende bericht
U kunt het bericht vooraan in een wachtrij bekijken zonder het uit de wachtrij te verwijderen door de methode peek_message aan te 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;
Hoe de inhoud van een bericht in de wachtrij te wijzigen
U kunt de inhoud van een bericht ter plaatse 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 wachtrijbericht bijgewerkt met nieuwe inhoud en wordt de time-out voor zichtbaarheid ingesteld om nog eens 60 seconden uit te breiden. Hiermee wordt de werkstatus opgeslagen die aan het bericht is gekoppeld en geeft de client nog een minuut om door te gaan met het werken aan het bericht. 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. Normaal gesproken houdt u ook het aantal nieuwe pogingen bij en als het bericht meer dan n keer opnieuw wordt geprobeerd, verwijdert u het. Dit beschermt tegen een bericht dat een toepassingsfout activeert telkens wanneer deze wordt 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;
Hoe: Het volgende bericht uit de wachtrij halen
Uw code verwijdert in twee stappen een bericht uit een wachtrij. Wanneer u get_messagebelt, krijgt u het volgende bericht in een wachtrij. Een bericht dat wordt geretourneerd vanuit get_message wordt onzichtbaar voor andere code die berichten uit deze wachtrij leest. Als u het bericht uit de wachtrij wilt verwijderen, moet u ook delete_messageaanroepen. Dit proces van twee stappen voor het verwijderen van een bericht zorgt ervoor dat als uw code een bericht niet kan verwerken vanwege hardware- of softwarefouten, een ander exemplaar van uw code hetzelfde bericht kan krijgen en het opnieuw kan proberen. Uw code roept delete_message direct nadat 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);
Hoe: Aanvullende opties gebruiken voor het uit de rij halen van berichten
Er zijn twee manieren waarop u het ophalen van berichten vanuit een wachtrij kunt aanpassen. Eerst kunt u een batch berichten ophalen (maximaal 32). Ten tweede kunt u een langere of kortere time-out voor onzichtbaarheid instellen, zodat uw code meer of minder tijd heeft om elk bericht volledig te verwerken. In het volgende codevoorbeeld wordt de methode get_messages gebruikt om 20 berichten in één aanroep op te halen. Vervolgens wordt elk bericht verwerkt met behulp van een for lus. Ook wordt de time-out voor onzichtbaarheid ingesteld op vijf minuten voor elk bericht. Houd er rekening mee dat de vijf minuten voor alle berichten tegelijk worden gestart, dus nadat vijf minuten zijn verstreken sinds de aanroep naar get_messages, worden alle berichten die niet zijn verwijderd, opnieuw 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;
}
Hoe de lengte van de wachtrij te achterhalen
U kunt een schatting krijgen van het aantal berichten in een wachtrij. De methode download_attributes retourneert wachtrijeigenschappen, inclusief het aantal berichten. Met de methode approximate_message_count 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;
Hoe een wachtrij te verwijderen
Als u een wachtrij en alle berichten in de wachtrij 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 basisprincipes van Queue Storage hebt geleerd, volgt u deze koppelingen voor meer informatie over Azure Storage.