如何使用來自C++的佇列記憶體

發行項
07/16/2020

小提示

嘗試Microsoft Azure 記憶體總管

Microsoft Azure 儲存體總管是一個免費的獨立應用程式，可讓您在 Windows、MacOS 和 Linux 上以視覺化方式處理 Azure 儲存體資料。

概觀

本指南將示範如何使用 Azure 佇列記憶體服務來執行常見案例。這些範例是以 C++ 撰寫，並使用 Azure 記憶體用戶端連結庫進行 C++。涵蓋的案例包括插入、查看、取得，以及刪除佇列訊息，以及 建立和刪除佇列。

備註

本指南以 C++ v1.0.0 和更新版本的 Azure 儲存體用戶端程式庫為目標。建議的版本是 Azure 記憶體用戶端連結庫 v2.2.0，可透過 NuGet 或 GitHub取得。

什麼是佇列記憶體？

Azure 佇列記憶體是一項服務，可用來儲存大量訊息，可透過 HTTP 或 HTTPS 的已驗證呼叫從世界各地存取。單一佇列訊息的大小最多可達 64 KB，而佇列可以包含數百萬則訊息，最多可達記憶體帳戶的總容量限制。佇列儲存通常用來建立工作積壓，以異步處理。

佇列服務概念

Azure 佇列服務包含下列元件：

Azure 佇列服務元件

記憶體帳戶： 所有對 Azure 記憶體的存取都是透過記憶體帳戶完成。如需儲存體帳戶的詳細資訊，請參閱儲存體帳戶概觀。
佇列：佇列包含一組訊息。所有訊息都必須在佇列中。請注意，佇列名稱必須全部小寫。如需為佇列命名的詳細資訊，請參閱為佇列和中繼資料命名。
訊息：大小上限為 64 KB 的訊息 (任何格式)。訊息可以保留在佇列中的時間上限為 7 天。在 2017-07-29 版或更新版本中，存留時間上限可以是任何正數或 -1 (表示訊息不會過期)。如果省略此參數，則預設存留時間為七天。
URL 格式： 佇列可以使用下列 URL 格式尋址：http://<storage account>.queue.core.windows.net/<queue>

下列 URL 指向圖表中的佇列：

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

建立 Azure 儲存體帳戶

建立第一個 Azure 記憶體帳戶最簡單的方式是使用 Azure 入口網站。若要深入了解，請參閱建立儲存體帳戶。

您也可以使用 Azure PowerShell、Azure CLI或適用於 .NET 的 Azure 記憶體資源提供者來建立 Azure 記憶體帳戶。

如果您目前不想在 Azure 中建立記憶體帳戶，您也可以使用 Azurite 記憶體模擬器在本機環境中執行和測試程式代碼。如需詳細資訊，請參閱使用 Azurite 模擬器進行本機 Azure 記憶體開發。

建立 C++ 應用程式

在本指南中，您將使用可在C++應用程式中執行的記憶體功能。

若要這樣做，您必須安裝適用於 C++ 的 Azure 記憶體用戶端連結庫，並在 Azure 訂用帳戶中建立 Azure 記憶體帳戶。

若要安裝適用於 C++ 的 Azure 記憶體用戶端連結庫，您可以使用下列方法：

Linux： 遵循適用於 C++ 的 Azure 儲存用戶端程式庫自述檔中提供的指示：開始使用 Linux 頁面。
Windows：在 Windows 上，請使用 vcpkg 作為相依性管理員。請遵循快速入門來初始化 vcpkg。然後，使用下列命令安裝函式庫：

.\vcpkg.exe install azure-storage-cpp

您可以在自述檔中找到如何建置原始程式碼並匯出至 NuGet 的指南。

設定您的應用程式以存取佇列記憶體

將下列 include 語句新增至您想要使用 Azure 記憶體 API 來存取佇列的C++檔案頂端：

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

設定 Azure 儲存體連接字串

Azure 記憶體用戶端會使用記憶體連接字串來儲存端點和認證，以存取資料管理服務。在用戶端應用程式中執行時，您必須以下列格式提供儲存連接字串，使用儲存帳戶的名稱，以及 Azure 入口網站中所列儲存帳戶的儲存存取金鑰作為，AccountName 和 AccountKey 的值。如需記憶體帳戶和存取金鑰的相關信息，請參閱關於 Azure 記憶體帳戶。本範例將示範如何宣告靜態欄位來存放連接字串：

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

若要在本機 Windows 電腦上測試您的應用程式，您可以使用 Azurite 記憶體模擬器。 Azurite 是一個公用程式，可模擬本機開發計算機上的 Azure Blob 記憶體和佇列記憶體。下列範例示範如何宣告靜態字位來保存本機記憶體模擬器的連接字串：

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

若要啟動 Azurite，請參閱使用 Azurite 模擬器進行本機 Azure 記憶體開發。

下列範例假設您已使用這兩種方法之一來取得記憶體連接字串。

擷取連接字串

您可以使用 cloud_storage_account 類別來代表儲存體帳戶資訊。若要從記憶體連接字串擷取記憶體帳戶資訊，您可以使用 parse 方法。

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

如何：建立佇列

cloud_queue_client 物件可讓您取得佇列的參考物件。下列程式代碼會建立 cloud_queue_client 物件。

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

使用 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();

作法：將訊息插入佇列

若要將訊息插入現有佇列，請先建立新的 cloud_queue_message。接著呼叫 add_message 方法。您可以從字串 (採用 UTF-8 格式) 或位元組陣列建立 cloud_queue_message。以下是建立佇列的程式代碼（如果佇列不存在），並將訊息插入 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);

如何：查看下一則訊息

透過呼叫 peek_message 方法，您可以在佇列前面查看訊息，而無需將其從佇列中移除。

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

如何：變更佇列訊息的內容

您可以直接在佇列中變更訊息的內容。如果訊息代表工作工作，您可以使用此功能來更新工作工作的狀態。下列程式代碼會以新的內容更新佇列訊息，並設定可見性逾時以再延長 60 秒。這會儲存與訊息相關聯的工作狀態，並再讓用戶端再一分鐘繼續處理訊息。您可以使用這項技術來追蹤佇列訊息上的多步驟工作流程，而不需要從頭開始開始，如果處理步驟因硬體或軟體失敗而失敗。一般而言，您也會保留重試計數，而且如果訊息重試超過 n 次，則會將其刪除。這可防止在處理時，每次都有觸發應用程式錯誤的訊息。

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

作法：清除下一則訊息

您的程式碼以兩個步驟從佇列中移出一個訊息。當您呼叫 get_message時，您會在佇列中取得下一個訊息。讀取此佇列訊息的任何其他程式碼皆無法看到從 get_message 傳回的訊息。若要完成從佇列中移除訊息，您也必須呼叫 delete_message。這個刪除訊息的兩步驟流程可確保當程式碼因硬體或軟體故障而無法處理訊息時，程式碼的其他執行個體可取得相同訊息並再試一次。已處理訊息後，程式碼便會立即呼叫 delete_message。

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

如何：使用其他選項來清除佇列訊息

有兩種方式可以自訂從佇列擷取訊息的方式。首先，您可以取得一批訊息（最多32則）。其次，您可以設定較長或較短的隱性逾時，讓您的程式代碼有或多或少的時間完整處理每個訊息。下列程式碼範例將使用 get_messages 方法，在一次呼叫中取得 20 個訊息。接著其會使用 for 迴圈處理每個訊息。它也會將不可見逾時設定為每則訊息五分鐘。請注意，所有訊息的五分鐘都會同時開始，因此在呼叫 get_messages之後五分鐘之後，任何尚未刪除的訊息都會再次顯示。

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

如何：取得佇列長度

您可估計佇列中的訊息數目。 download_attributes 方法會傳回佇列屬性，包括訊息計數。 approximate_message_count 方法會取得佇列中訊息的近似數目。

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

如何：刪除佇列

若要刪除佇列及其中包含的所有訊息，請在佇列物件上呼叫 delete_queue_if_exists 方法。

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

後續步驟

既然您已瞭解佇列記憶體的基本概念，請遵循這些連結以深入瞭解 Azure 記憶體。

如何使用來自C++ 的 Blob 記憶體
如何使用來自C++ 的數據表記憶體
以 C++ 列出 Azure 儲存體資源
適用於C++參考的 Azure 記憶體用戶端連結庫
Azure 儲存體文件

共用方式為