如何使用 C++ 的佇列儲存體

概觀

本指南將示範如何使用 Azure 佇列儲存體服務執行一般案例。 這些範例均以 C++ 撰寫，並使用適用於 C++ 的 Azure 儲存體用戶端程式庫。 所涵蓋的案例包括「插入」、「查看」、「取得」和「刪除」佇列訊息，以及「建立和刪除佇列」。

什麼是佇列儲存體？

Azure 佇列儲存體是一項儲存大量訊息的服務，全球任何地方都可利用 HTTP 或 HTTPS 並透過驗證的呼叫來存取這些訊息。 單一佇列訊息的大小上限為 64 KB，而一個佇列可以包含數百萬個訊息，以儲存體帳戶的總容量為限。 佇列儲存體通常用來建立要以非同步方式處理的待處理項目。

佇列服務概念

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

• 儲存體帳戶： 一律透過儲存體帳戶來存取 Azure 儲存體。 如需儲存體帳戶的詳細資訊，請參閱儲存體帳戶概觀。

• 佇列： 佇列包含一組訊息。 所有訊息都必須放在佇列中。 請注意，佇列名稱必須是小寫。 如需為佇列命名的詳細資訊，請參閱 為佇列和中繼資料命名。

• 訊息： 大小上限為 64 KB 的訊息 (任何格式)。 訊息可保留在佇列中的時間上限為 7 天。 如需版本 2017-07-29 或更新版本，最大存留時間可以是任何正數，或是表示訊息未過期的 -1。 如果省略此參數，則預設存留時間為 7 天。

• 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，或 Azure Storage Resource Provider for .NET 來建立 Azure 儲存體帳戶。

如果您不想此時在 Azure 中建立儲存體帳戶，也可以使用 Azure 儲存體模擬器在本機環境中執行並測試您的程式碼。 如需詳細資訊，請參閱使用 Azure 模擬器進行本機 Azure 儲存體開發。

建立 C++ 應用程式

在本指南中，您將使用可以在 C++ 應用程式內執行的儲存體功能。

若要這樣做，您需要安裝適用於 C++ 的 Azure 儲存體用戶端程式庫，並在 Azure 訂用帳戶中建立 Azure 儲存體帳戶。

若要安裝適用於 C++ 的 Azure 儲存體用戶端程式庫，您可以使用下列方法：

• Linux：依照適用於 C++ 的 Azure 儲存體用戶端程式庫讀我檔案：在 Linux 上開始使用頁面中提供的指示操作。
• Windows： 在 Windows 上，請使用 vcpkg 作為相依性管理員。 依照快速入門進行初始化vcpkg。 然後，使用下列命令安裝二進位檔：

.\vcpkg.exe install azure-storage-cpp

您可以在讀我檔案檔案中找到建置原始程式碼及匯出至 NuGet 的指南。

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

在您要使用 Azure 儲存體 API 來存取佇列的 C++ 檔案頂端，加入下列 include 陳述式：

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

設定 Azure 儲存體連接字串

Azure 儲存體用戶端會使用儲存體連接字串來儲存存取資料管理服務時所用的端點與認證。 在用戶端應用程式中執行時，您必須以下列格式提供儲存體連接字串 (其中 AccountName 和 AccountKey 的值要使用您儲存體帳戶的名稱和在 Azure 入口網站中針對該儲存體帳戶而列出的儲存體存取金鑰)。 如需有關儲存體帳戶和存取金鑰的資訊，請參閱關於 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 迴圈處理每個訊息。 它也會將可見度逾時設定為每個訊息五分鐘。 請注意，系統會針對所有訊息同時開始計時 5 分鐘，所以從呼叫 get_messages 開始的 5 分鐘後，任何尚未刪除的訊息都會重新出現。

// 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 儲存體文件