快速入門：適用於 C++ 的 Azure Blob 儲存體用戶端程式庫

開始使用適用於 C++ 的 Azure Blob 儲存體用戶端程式庫。 Azure Blob 儲存體是 Microsoft 的雲端物件儲存解決方案。 請遵循下列步驟來安裝套件，並試用基本工作的程式碼範例。

| API 參考文件 | 程式庫原始碼 | 範例 |

先決條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• C++編譯器
• CMake
• vcpkg - C 和 C++ 套件管理員

設定

本節會逐步引導您準備專案，以使用適用於 C++ 的 Azure Blob 儲存體用戶端程式庫。 取得適用於 C++ 的 Azure SDK 的最簡單方式是使用 vcpkg 套件管理員。

安裝套件

使用命令 vcpkg install 來安裝適用於 C++ 的 Azure Blob 儲存體程式庫和必要的相依性：

vcpkg.exe install azure-storage-blobs-cpp

為了無密碼連線到 Azure 服務，您需要 Azure 身分識別程式庫：

vcpkg.exe install azure-identity-cpp

如需有關專案設定和使用 C++ 版 Azure SDK 的詳細資訊，請參閱 Azure SDK for C++ 讀我 檔案。

建立專案

在 Visual Studio 中，建立名為 BlobQuickstart 的新 C++ 主控台應用程式。

物件模型

Azure Blob 儲存體已針對儲存大量非結構化資料進行了最佳化。 非結構化資料是不遵守特定資料模型或定義的資料，例如文字或二進位資料。 Blob 儲存體提供三種類型的資源：

• 儲存體帳戶
• 雲端儲存帳戶中的容器
• 容器中的 Blob

下圖顯示這些資源之間的關係。

使用這些 C++ 類別與這些資源互動：

• BlobServiceClient：類別可讓您 BlobServiceClient 操作 Azure 儲存體資源和 Blob 容器。
• BlobContainerClient：類別可讓您 BlobContainerClient 操作 Azure 儲存體容器及其 Blob 物件。
• BlobClient：此類別允許您操作 Azure 儲存體 Blob。 這是所有特製化 Blob 類別的基底類別。
• BlockBlobClient：BlockBlobClient 類別可讓您操作 Azure 儲存體區塊 Blob。

程式碼範例

這些範例程式碼片段示範如何使用適用於 C++ 的 Azure Blob 儲存體用戶端程式庫執行下列工作：

• 新增包含檔案
• 向 Azure 進行驗證，並授權存取 Blob 資料
• 建立容器
• 將 Blob 上傳至容器
• 列出容器中的 Blob
• 下載 Blob
• 刪除容器

新增包含檔案

從專案目錄：

1. 在 Visual Studio 中開啟 BlobQuickstart.sln 解決方案檔案
2. 在 Visual Studio 中，開啟 BlobQuickstart.cpp 原始檔
3. 刪除內部 main 自動生成的任何代碼
4. 新增 #include 和 using namespace 陳述式

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

向 Azure 驗證，並授權存取 Blob 資料

應用程式向 Azure Blob 儲存體提出的要求必須經過授權。 使用 DefaultAzureCredential Azure 身分識別用戶端程式庫所提供的類別，是在程式碼中實作 Azure 服務 （包括 Blob 儲存體） 的無密碼連線的建議方法。

您也可以使用帳戶存取金鑰，以授權對 Azure Blob 儲存體的要求。 不過，應該謹慎使用此方法。 開發人員必須盡可能避免在不安全的地方公開存取金鑰。 任何擁有存取金鑰的人都可以授權執行目標為儲存體帳戶的要求，而且可實質存取所有資料。 DefaultAzureCredential 提供優於帳戶金鑰的管理和安全性優點，允許無密碼驗證。 下列範例示範這兩個選項。

無密碼 (建議)

Azure 身分識別程式庫提供跨 Azure SDK 的 Microsoft Entra 權杖驗證支援。 它提供一組 TokenCredential 實作，可用來建構支援 Microsoft Entra 權杖驗證的 Azure SDK 用戶端。 DefaultAzureCredential 支援多種身份驗證方法，並決定在運行時應該使用哪種方法。

將角色指派給 Microsoft Entra 使用者帳戶

在本機開發時，請確定存取 Blob 資料的使用者帳戶具有正確的權限。 您需要儲存體 Blob 資料參與者才能讀取和寫入 Blob 資料。 若要指派此角色給您自己，您需要被指派使用者存取管理員角色，或另一個包含 Microsoft.Authorization/roleAssignments/write 動作的角色。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell，將 Azure RBAC 角色指派給使用者。 如需儲存體 Blob 資料參與者角色的詳細資訊，請參閱儲存體 Blob 資料參與者。 如需角色指派可用範圍的詳細資訊，請參閱了解 Azure RBAC 的範圍。

在此案例中，您會將權限指派給使用者帳戶 (以儲存體帳戶為範圍)，以遵循最低權限原則。 此做法只為使用者提供所需的最低權限，並建立更安全的實際執行環境。

下列範例將儲存體 Blob 資料參與者角色指派給使用者帳戶，以針對儲存體帳戶中的 Blob 資料提供讀取和寫入存取權。

這很重要

在大部分情況下，角色指派在 Azure 中傳播只需要一兩分鐘，但在罕見情況下，可能需要長達八分鐘。 如果您第一次執行程式碼時收到驗證錯誤，請稍候片刻再試一次。

Azure 入口網站

1. 在 Azure 入口網站中，使用主要搜尋列或左側導覽找出您的儲存體帳戶。

2. 在儲存體帳戶概觀頁面上，從左側功能表中選取 [存取控制 (IAM)]。

3. 在 [存取控制 (IAM)] 頁面上，選取 [角色指派] 索引標籤。

4. 從頂端功能表中選取 [+ 新增 ]，然後從產生的下拉式功能表中選取 [ 新增角色指派 ]。

   

5. 使用搜尋方塊，從結果篩選出所需的角色。 在此範例中，搜尋「儲存體 Blob 資料參與者」，選取相符的結果，然後選擇 [下一步]。

6. 在 [存取權指派對象為] 下，選取 [使用者、群組或服務主體]，然後選擇 [+ 選取成員]。

7. 在對話方塊中，搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址)，然後在對話方塊底部選擇 [選取]。

8. 選取 [檢閱 + 指派] 以移至最終頁面，然後再次選取 [檢閱 + 指派] 以完成此程序。

Azure CLI

若要使用 Azure CLI 在資源層級指派角色，您必須先使用 az storage account show 命令擷取資源識別碼。 您可以使用 --query 參數來篩選輸出屬性。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

複製上述命令的輸出 Id。 接著，您可以使用 Azure CLI 的 az role 命令來指派角色。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

若要使用 Azure PowerShell 在資源層級指派角色，您必須先使用 Get-AzResource 命令擷取資源識別碼。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

複製上述命令輸出的 Id 值。 接著，您可以在 PowerShell 中使用 New-AzRoleAssignment 命令來指派角色。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

使用 DefaultAzureCredential 登入並將應用程式程式碼連線到 Azure

您可以使用下列步驟來授權存取儲存體帳戶中的資料：

1. 請確定使用您在儲存體帳戶上指派角色的相同 Microsoft Entra 帳戶進行驗證。 您可以透過 Azure CLI 進行驗證。 使用下列命令，透過 Azure CLI 登入 Azure：

   az login
   

2. 若要使用 DefaultAzureCredential，請確定已安裝azure-identity-cpp 套件，並新增下列 #include：

   #include <azure/identity/default_azure_credential.hpp>
   

3. 將此程式碼新增至 的結尾 main()。 當程式碼在本機工作站上執行時， DefaultAzureCredential 會使用 Azure CLI 的開發人員認證來向 Azure 進行驗證。

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. 請務必更新物件 URI BlobServiceClient 中的儲存體帳戶名稱。 儲存體帳戶名稱可以在 Azure 入口網站的概觀頁面上找到。

   

   備註

   在生產環境中使用 C++ SDK 時，建議您只啟用您知道應用程式將使用的認證。 建議您不要使用 DefaultAzureCredential，而是應該授權使用特定的認證類型，或者使用支援的認證搭配 ChainedTokenCredential 來授權。

連接字串

連接字串包含儲存體帳戶存取金鑰，可用來授權要求。 請務必小心，絕不要在不安全的地方公開金鑰。

備註

若要使用儲存體帳戶存取金鑰授權資料存取，您需要下列 Azure RBAC 動作的許可權： Microsoft.Storage/storageAccounts/listkeys/action。 具有此動作許可權的最低權限內建角色是 「讀者」和「資料存取」，但任何包含此動作的角色都可以運作。

Azure 入口網站

1. 登入 Azure 入口網站。

2. 定位您的儲存體帳戶。

3. 在 [儲存體帳戶] 功能表窗格的 [安全性 + 網路] 下方，選取 [存取金鑰]。 在這裡，您可以檢視帳戶存取金鑰和每個金鑰的完整連接字串。

4. 在 [存取金鑰 ] 窗格中，選取 [ 顯示金鑰]。

5. 在 key1 區段中，找出 [連接字串] 值。 選取 [複製到剪貼簿] 圖示以複製連接字串。 您會在下一節中將連接字串值新增至環境變數。

   

Azure CLI

您可以使用 az storage account show-connection-string 命令來查看儲存體帳戶的連接字串。

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

您可以使用 Get-AzStorageAccount 和 Get-AzStorageAccountKey 命令，使用 PowerShell 組合連接字串。

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

設定您的儲存體連接字串

複製連接字串之後，請將它寫入執行應用程式的本機電腦上的新環境變數。 若要設定環境變數，請開啟主控台視窗，然後遵循作業系統的指示。 將 <yourconnectionstring> 用實際的連接字串取代。

Windows：

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中新增環境變數之後，您必須啟動新的命令視窗執行個體。

Linux：

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

下列程式碼範例會從稍早建立的環境變數擷取儲存體帳戶的連接字串，並使用連接字串來建構服務用戶端物件。

新增此程式碼至 main() 的結尾：

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

這很重要

應該謹慎使用帳戶存取金鑰。 如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。 任何擁有存取金鑰的人都可以授權執行目標為儲存體帳戶的要求，而且可實質存取所有資料。 DefaultAzureCredential 會提供增強的安全性功能和優點，建議用來管理對 Azure 服務的授權。

建立容器

決定新容器的名稱。 然後建立 的 BlobContainerClient 實例並建立容器。

這很重要

容器名稱必須是小寫字母。 如需命名容器和 Blob 的詳細資訊，請參閱 命名和參考容器、Blob 和中繼資料。

新增此程式碼至 main() 的結尾：

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

將 Blob 上傳至容器

以下程式碼片段：

1. 宣告一個包含「Hello Azure！」的字串
2. 從 [建立容器] 區段，透過在容器上呼叫 GetBlockBlobClient 來取得 BlockBlobClient 物件的參考。
3. 呼叫 UploadFrom 函式，將字串上傳至 Blob。 如果 Blob 尚不存在，則此函式會建立 Blob，如果存在，則會更新它。

新增此程式碼至 main() 的結尾：

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

列出容器中的 Blob

呼叫 ListBlobs 函式，列出容器中的 Blob。 只有一個 Blob 新增至容器，因此作業只會傳回該 Blob。

新增此程式碼至 main() 的結尾：

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

下載 Blob

取得上傳 Blob 的屬性。 然後，使用上傳 Blob 的屬性來宣告新物件並調整其 std::vector<uint8_t> 大小。 呼叫 std::vector<uint8_t> 基類中的 DownloadTo 函式，將先前建立的 Blob 下載到新物件中。 最後，顯示下載的 blob 資料。

新增此程式碼至 main() 的結尾：

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

刪除 Blob

下列程式碼會呼叫 BlobClient.Delete 函式，從 Azure Blob 儲存體容器中刪除 Blob。

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

刪除容器

下列程式碼會使用 BlobContainerClient 刪除整個容器，以清除應用程式所建立的資源 。刪除。

新增此程式碼至 main() 的結尾：

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

執行程式碼

此應用程式會建立容器，並將文字檔上傳至 Azure Blob 儲存體。 然後，此範例會列出容器中的 Blob、下載檔案，並顯示檔案內容。 最後，應用程式會刪除 Blob 和容器。

應用程式的輸出類似下列範例：

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

後續步驟

在本快速入門中，您已瞭解如何使用 C++ 上傳、下載和列出 Blob。 您也瞭解如何建立和刪除 Azure Blob 儲存體容器。

若要查看 C++ Blob 儲存體範例，請繼續：

適用於 C++ 範例的 Azure Blob 儲存體用戶端程式庫