Queue Storage gebruiken met C++

Overzicht

In deze handleiding ziet u hoe u algemene scenario's kunt uitvoeren met behulp van de Azure Queue Storage service. De voorbeelden zijn geschreven in C++ en maken gebruik van Azure Storage clientbibliotheek voor C++. De scenario's die worden behandeld, zijn onder andere het invoegen, bekijken, ontvangen en verwijderen van wachtrijberichten, en het maken en verwijderen van wachtrijen.

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 te maken voor het asynchroon verwerken van werk.

Concepten van Queue-service

De Azure Queue-service bevat de volgende onderdelen:

• Opslag account: Alle toegang tot Azure Storage wordt uitgevoerd via een opslag account. 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: Wacht rijen zijn adresseerbaar met behulp van 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-opslag account 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 opslag account maakt in azure, kunt u ook de Azurite-opslag emulator gebruiken om uw code uit te voeren en te testen in een lokale omgeving. Zie voor meer informatie de Azurite-emulator gebruiken voor het ontwikkelen van lokale Azure Storage.

Een C++-toepassing maken

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

Als u dit wilt doen, moet u de Azure Storage-clientbibliotheek voor C++ installeren en een Azure Storage 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 in de Azure Storage-clientbibliotheek voor C++ README: Aan de slag linux-pagina.
• Windows: In Windows gebruikt u vcpkg als afhankelijkheidsbeheerder. Volg de quickstart om te initialiseren. vcpkg 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 LEESMIJ-bestand.

Uw toepassing configureren voor toegang tot Queue Storage

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

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

Een Azure-opslagverbindingstekenreeks instellen

Een Azure Storage-client gebruikt een connection string eindpunten en referenties op te slaan voor toegang tot services voor gegevensbeheer. Bij uitvoering in een clienttoepassing moet u de opslag-connection string in de volgende indeling verstrekken met behulp van de naam van uw opslagaccount en de toegangssleutel voor opslag voor het opslagaccount dat wordt vermeld in de Azure Portal voor de waarden AccountName en AccountKey . Zie About Azure Storage accounts (Informatie over opslagaccounts en toegangssleutels) Azure Storage 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 Windows computer, kunt u de Azurite-opslagemulator gebruiken. Azurite is een hulpprogramma dat Azure Blob Storage en Queue Storage op uw lokale ontwikkelmachine simuleert. 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 De Azurite-emulatorgebruiken 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 connection string opslagaccount, 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);

Een wachtrij maken

Met cloud_queue_client een -object kunt u referentieobjecten voor wachtrijen op halen. 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 nog 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();  

Hoe: Een bericht in een wachtrij invoegen

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 vanuit een tekenreeks (in UTF-8-indeling) of een byte-matrix. Dit is de code waarmee een wachtrij wordt gemaakt (als deze nog niet bestaat) en het bericht Hello, World invoegt:

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

Hoe: Het volgende bericht bekijken

U kunt het bericht vooraan in een wachtrij bekijken 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;

Hoe: 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 bij te houden voor wachtrijberichten, zonder dat u vanaf het begin opnieuw moet beginnen als een verwerkingsstap mislukt vanwege hardware- of softwarefout. 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;  

How to: Het volgende bericht uit dequeque

Met uw code wordt in twee stappen een bericht uit een wachtrij verwijderd. Wanneer u get_message aanroept, krijgt u het volgende bericht in een wachtrij. Een bericht dat wordt geretourneerd get_message door wordt onzichtbaar voor andere code die berichten uit deze wachtrij leest. Als u het bericht uit de wachtrij wilt verwijderen, moet u ook delete_message aanroepen. 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 delete_message aan 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);

How to: Use additional options for dequeuing messages (Aanvullende opties gebruiken voor het uit dequequeneren 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 beginnen, dus nadat vijf minuten zijn verstreken sinds de aanroep van , worden alle berichten die niet zijn verwijderd, weer get_messages 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 op te halen

U kunt een schatting ophalen van het aantal berichten in de wachtrij. De download_attributes methode retourneert wachtrijeigenschappen, inclusief het aantal berichten. De approximate_message_count methode haalt het geschatte aantal berichten in de wachtrij op.

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

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.

• Blob-Storage gebruiken vanuit C++
• Table-Storage gebruiken vanuit C++
• Azure Storage-resources in C++ weergeven
• Azure Storage-clientbibliotheek voor C++-naslag
• Documentatie voor Azure Storage