Jak używać usługi Queue Storage z poziomu języka C++

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

Porada

Wypróbuj program Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer jest bezpłatną aplikacją autonomiczną oferowaną przez firmę Microsoft, która umożliwia wizualną pracę z danymi w usłudze Azure Storage w systemach Windows, macOS i Linux.

Omówienie

W tym przewodniku pokazano, jak wykonać typowe scenariusze przy użyciu usługi Azure Queue Storage. Przykłady są napisane w języku C++ i używają biblioteki klienta usługi Azure Storage dla języka C++. Omówione scenariusze obejmują wstawianie, podgląd, pobieranie i usuwanie komunikatów kolejki, a także tworzenie i usuwanie kolejek.

Uwaga

Ten przewodnik jest przeznaczony dla biblioteki klienta usługi Azure Storage dla języka C++ w wersji 1.0.0 lub nowszej. Zalecaną wersją jest biblioteka klienta usługi Azure Storage w wersji 2.2.0, która jest dostępna za pośrednictwem narzędzia NuGet lub GitHub.

Co to jest usługa Queue Storage?

Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów, do której można uzyskać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionego połączenia za pomocą protokołu HTTP lub HTTPS. Pojedynczy komunikat z kolejki nie może przekraczać 64 KB, a kolejka może zawierać miliony komunikatów — maksymalnie liczbę nieprzekraczającą całkowitego limitu pojemności konta magazynu. Usługa Queue Storage jest często używana do tworzenia listy prac w celu przetwarzania asynchronicznego.

Pojęcia dotyczące usługi kolejki

Usługa Azure Queue service zawiera następujące składniki:

• Konto magazynu: cały dostęp do usługi Azure Storage odbywa się przez konto magazynu. Aby uzyskać więcej informacji na temat kont magazynu, zobacz Omówienie konta magazynu.

• Kolejka: kolejka zawiera zestaw komunikatów. Wszystkie komunikaty muszą być w kolejce. Pamiętaj, że nazwa kolejki może zawierać tylko małe litery. Informacje dotyczące nazewnictwa kolejek można znaleźć w temacie Naming Queues and Metadata (Nazewnictwo kolejek i metadanych).

• Komunikat: komunikat w dowolnym formacie, o maksymalnym rozmiarze 64 KB. Maksymalny czas pozostawania komunikatu w kolejce wynosi 7 dni. W przypadku wersji 2017-07-29 lub nowszej maksymalny czas wygaśnięcia może być dowolną liczbą dodatnią lub -1 wskazującą, że komunikat nie wygaśnie. Jeśli ten parametr zostanie pominięty, domyślny czas wygaśnięcia wynosi siedem dni.

• Format adresu URL: Kolejki są adresowalne przy użyciu następującego formatu adresu URL: http://<storage account>.queue.core.windows.net/<queue>

  Następujący adres URL dotyczy kolejki w schemacie:

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

Tworzenie konta usługi Azure Storage

Najprościej jest utworzyć pierwsze konto usługi Azure Storage przy użyciu witryny Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.

Można również utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell, interfejsu wiersza polecenia Azure lub dostawcy zasobów usługi Azure Storage dla platformy .NET.

Jeśli w tej chwili nie chcesz tworzyć konta magazynu na platformie Azure, możesz również użyć emulatora magazynu Azurite, aby uruchomić i przetestować kod w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Tworzenie aplikacji języka C++

W tym przewodniku użyjesz funkcji magazynu, które można uruchomić w aplikacji języka C++.

W tym celu należy zainstalować bibliotekę klienta usługi Azure Storage dla języka C++ i utworzyć konto usługi Azure Storage w ramach subskrypcji platformy Azure.

Aby zainstalować bibliotekę klienta usługi Azure Storage dla języka C++, można użyć następujących metod:

• Linux: Postępuj zgodnie z instrukcjami podanymi w bibliotece klienta usługi Azure Storage dla pliku README języka C++: Wprowadzenie na stronie systemu Linux.
• Windows: W systemie Windows użyj narzędzia vcpkg jako menedżera zależności. Postępuj zgodnie z przewodnikiem Szybki start , aby zainicjować vcpkgelement . Następnie użyj następującego polecenia, aby zainstalować bibliotekę:

.\vcpkg.exe install azure-storage-cpp

Przewodnik dotyczący tworzenia kodu źródłowego i eksportowania do narzędzia NuGet można znaleźć w pliku README .

Konfigurowanie aplikacji w celu uzyskania dostępu do usługi Queue Storage

Dodaj następujące instrukcje dołączania do góry pliku C++, w którym chcesz używać interfejsów API usługi Azure Storage do uzyskiwania dostępu do kolejek:

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

Konfigurowanie parametrów połączenia usługi Azure Storage

Klient usługi Azure Storage używa parametrów połączenia magazynu do przechowywania punktów końcowych i poświadczeń na potrzeby uzyskiwania dostępu do usług zarządzania danymi. Podczas uruchamiania w aplikacji klienckiej należy podać parametry połączenia magazynu w następującym formacie, używając nazwy konta magazynu i klucza dostępu magazynu dla konta magazynu wymienionego w Azure Portal wartości AccountName iAccountKey. Aby uzyskać informacje na temat kont magazynu i kluczy dostępu, zobacz About Azure Storage accounts (Informacje o kontach usługi Azure Storage). W tym przykładzie pokazano, jak można zadeklarować pole statyczne w celu przechowywania parametrów połączenia:

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

Aby przetestować aplikację na lokalnym komputerze z systemem Windows, możesz użyć emulatora magazynu Azurite. Azurite to narzędzie, które symuluje Azure Blob Storage i Queue Storage na lokalnej maszynie programistycznej. W tym przykładzie pokazano, jak można zadeklarować pole statyczne w celu przechowywania parametrów połączenia z lokalnym emulatorem magazynu:

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

Aby uruchomić usługę Azurite, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

W poniższych przykładach założono, że uzyskano parametry połączenia za pomocą jednej z tych dwóch metod.

Pobieranie parametrów połączenia

Możesz użyć cloud_storage_account klasy do reprezentowania informacji o koncie magazynu. Aby pobrać informacje o koncie magazynu z parametrów połączenia magazynu, możesz użyć parse metody .

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

Instrukcje: tworzenie kolejki

Obiekt cloud_queue_client umożliwia uzyskiwanie obiektów referencyjnych dla kolejek. Poniższy kod tworzy cloud_queue_client obiekt.

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

Użyj obiektu , cloud_queue_client aby uzyskać odwołanie do kolejki, której chcesz użyć. Jeśli kolejka nie istnieje, możesz utworzyć kolejkę.

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

Instrukcje: wstawianie komunikatu do kolejki

Aby wstawić komunikat do istniejącej kolejki, najpierw utwórz nowy cloud_queue_messageelement . Następnie wywołaj metodę add_message . Element cloud_queue_message można utworzyć na podstawie ciągu (w formacie UTF-8) lub tablicy bajtów. Oto kod, który tworzy kolejkę (jeśli nie istnieje) i wstawia komunikat 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);  

Instrukcje: Przeglądanie następnego komunikatu

Komunikat można wyświetlić przed kolejką bez usuwania jej z kolejki przez wywołanie 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;

Instrukcje: zmienianie zawartości komunikatu w kolejce

Możesz zmienić zawartość komunikatu w kolejce. Jeśli komunikat reprezentuje zadanie robocze, możesz użyć tej funkcji, aby zaktualizować stan zadania. Poniższy kod aktualizuje komunikat kolejki o nową zawartość i ustawia rozszerzenie limitu czasu widoczności o kolejne 60 sekund. Operacja ta zapisuje stan pracy powiązanej z komunikatem i daje klientowi kolejną minutę na kontynuowanie pracy nad komunikatem. Można użyć tej techniki do śledzenia wieloetapowych przepływów pracy w komunikatach kolejki bez konieczności rozpoczynania się od początku, jeśli krok przetwarzania zakończy się niepowodzeniem z powodu awarii sprzętu lub oprogramowania. Zazwyczaj stosuje się również liczbę ponownych prób. Jeśli komunikat zostanie ponowiony więcej niż n razy, zostanie usunięty. Jest to zabezpieczenie przed komunikatami, które wyzwalają błąd aplikacji zawsze, gdy są przetwarzane.

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

Instrukcje: dequeue następnej wiadomości

Kod dequeuuje komunikat z kolejki w dwóch krokach. Po wywołaniu metody get_messagezostanie wyświetlony następny komunikat w kolejce. Komunikat zwrócony z get_message staje się niewidoczny dla każdego innego kodu odczytujących komunikaty z tej kolejki. Aby zakończyć usuwanie komunikatu z kolejki, należy również wywołać metodę delete_message. Ten dwuetapowy proces usuwania komunikatów gwarantuje, że jeśli kod nie będzie w stanie przetworzyć komunikatu z powodu awarii sprzętu lub oprogramowania, inne wystąpienie kodu będzie w stanie uzyskać ten sam komunikat i ponowić próbę. Kod wywołuje się delete_message bezpośrednio po przetworzeniu komunikatu.

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

Instrukcje: używanie dodatkowych opcji usuwania komunikatów w kolejce

Istnieją dwa sposoby dostosowania pobierania komunikatów z kolejki. Po pierwsze można uzyskać komunikaty zbiorczo (do 32). Po drugie można ustawić dłuższy lub krótszy limit czasu niewidoczności, dzięki czemu kod będzie mieć więcej lub mniej czasu na pełne przetworzenie każdego komunikatu. Poniższy przykład kodu używa get_messages metody , aby uzyskać 20 komunikatów w jednym wywołaniu. Następnie przetwarza każdy komunikat przy użyciu for pętli. Ustawia również limitu czasu niewidoczności na pięć minut dla każdego komunikatu. Należy pamiętać, że pięć minut rozpoczyna się dla wszystkich komunikatów w tym samym czasie, więc po upływie pięciu minut od wywołania metody get_messages, wszystkie komunikaty, które nie zostały usunięte, staną się ponownie widoczne.

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

Instrukcje: uzyskiwanie długości kolejki

Możesz uzyskać szacunkową liczbę komunikatów w kolejce. Metoda download_attributes zwraca właściwości kolejki, w tym liczbę komunikatów. Metoda approximate_message_count pobiera przybliżoną liczbę komunikatów w kolejce.

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

Instrukcje: usuwanie kolejki

Aby usunąć kolejkę i wszystkie zawarte w nim komunikaty, wywołaj delete_queue_if_exists metodę w obiekcie kolejki.

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

Następne kroki

Teraz, gdy znasz już podstawy usługi Queue Storage, skorzystaj z tych linków, aby dowiedzieć się więcej o usłudze Azure Storage.

• Jak używać usługi Blob Storage z poziomu języka C++
• Jak używać usługi Table Storage z poziomu języka C++
• Generowanie listy zasobów usługi Azure Storage w języku C++
• Dokumentacja biblioteki klienta usługi Azure Storage dla języka C++
• Dokumentacja usługi Azure Storage