Rychlý start: Klientská knihovna Azure Blob Storage pro C++

Začínáme s klientskou knihovnou azure Blob Storage pro C++. Azure Blob Storage je řešení úložiště objektů Od Microsoftu pro cloud. Pomocí těchto kroků nainstalujte balíček a vyzkoušejte si ukázkový kód pro základní úlohy.

| Ukázky zdrojového kódu | knihovny referenční dokumentace | k rozhraní API |

Předpoklady

• Předplatné Azure – vytvoření bezplatného předplatného
• Účet úložiště Azure – Vytvoření účtu úložiště
• Kompilátor C++
• CMake
• vcpkg – správce balíčků C a C++

Nastavení

Tato část vás provede přípravou projektu pro práci s klientskou knihovnou služby Azure Blob Storage pro C++. Nejjednodušší způsob, jak získat sadu Azure SDK pro C++, je použít vcpkg správce balíčků.

Instalace balíčků

vcpkg install Pomocí příkazu nainstalujte knihovnu Azure Blob Storage pro C++ a potřebné závislosti:

vcpkg.exe install azure-storage-blobs-cpp

Knihovna identit Azure je potřebná pro připojení bez hesla ke službám Azure:

vcpkg.exe install azure-identity-cpp

Další informace o nastavení projektu a práci se sadou Azure SDK pro C++ najdete v souboru Readme sady Azure SDK pro jazyk C++.

Vytvoření projektu

V sadě Visual Studio vytvořte novou konzolovou aplikaci C++ pro Windows s názvem BlobQuickstart.

Objektový model

Azure Blob Storage je optimalizovaná pro ukládání obrovských objemů nestrukturovaných dat. Nestrukturovaná data jsou data, která neodpovídají žádnému konkrétnímu datovému modelu nebo definici, jako jsou textová nebo binární data. Blob Storage nabízí tři typy prostředků:

• Účet úložiště
• Kontejner v účtu úložiště
• Objekt blob v kontejneru

Na následujícím diagramu jsou vztahy těchto prostředků.

K interakci s těmito prostředky použijte tyto třídy jazyka C++:

• BlobServiceClient: Třída BlobServiceClient umožňuje manipulovat s prostředky azure Storage a kontejnery objektů blob.
• BlobContainerClient: Třída BlobContainerClient umožňuje manipulovat s kontejnery Azure Storage a jejich objekty blob.
• BlobClient: Třída BlobClient umožňuje manipulovat s objekty blob služby Azure Storage. Je to základní třída pro všechny specializované třídy objektů blob.
• BlockBlobClient: Třída BlockBlobClient umožňuje manipulovat s objekty blob bloku služby Azure Storage.

Příklady kódu

Tyto ukázkové fragmenty kódu ukazují, jak provádět následující úlohy s klientskou knihovnou služby Azure Blob Storage pro C++:

• Přidání souborů zahrnutí
• Ověřování v Azure a autorizace přístupu k datům objektů blob
• Vytvoření kontejneru
• Nahrání objektů blob do kontejneru
• Výpis objektů blob v kontejneru
• Stažení objektů blob
• Odstranění kontejneru

Přidání souborů zahrnutí

Z adresáře projektu:

1. Otevření souboru řešení BlobQuickstart.sln v sadě Visual Studio
2. V sadě Visual Studio otevřete zdrojový soubor BlobQuickstart.cpp .
3. Odeberte veškerý kód uvnitř main , který byl automaticky vygenerován.
4. Přidání #include a using namespace příkazy

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

Ověřování v Azure a autorizace přístupu k datům objektů blob

Žádosti aplikací do služby Azure Blob Storage musí být autorizované. DefaultAzureCredential Použití třídy poskytované klientskou knihovnou azure Identity je doporučeným přístupem k implementaci bez hesel připojení ke službám Azure v kódu, včetně blob Storage.

Žádosti o službu Azure Blob Storage můžete také autorizovat pomocí přístupového klíče účtu. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby nikdy nezpřístupnil přístupový klíč v nezabezpečeném umístění. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla. Obě možnosti jsou demonstrována v následujícím příkladu.

Bez hesla (doporučeno)

Knihovna Identit Azure poskytuje podporu ověřování tokenů Microsoft Entra napříč sadou Azure SDK. Poskytuje sadu TokenCredential implementací, které je možné použít k vytvoření klientů sady Azure SDK, které podporují ověřování tokenů Microsoft Entra. DefaultAzureCredential podporuje více metod ověřování a určuje, která metoda se má použít za běhu.

Přiřazení rolí k uživatelskému účtu Microsoft Entra

Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům objektů blob, má správná oprávnění. K čtení a zápisu dat objektů blob budete potřebovat Přispěvatel dat objektů blob služby Storage. Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli User Access Správa istrator nebo jinou roli, která zahrnuje akci Microsoft.Authorization/roleAssignments/write. Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o dostupných oborech pro přiřazení rolí najdete na stránce přehledu oboru.

V tomto scénáři přiřadíte oprávnění k vašemu uživatelskému účtu s vymezeným oborem účtu úložiště, abyste postupovali podle zásady nejnižších oprávnění. Tento postup poskytuje uživatelům jenom minimální potřebná oprávnění a vytváří bezpečnější produkční prostředí.

Následující příklad přiřadí roli Přispěvatel dat v objektech blob služby Storage k vašemu uživatelskému účtu, který poskytuje přístup ke čtení i zápisu k datům objektů blob v účtu úložiště.

Důležité

Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure, ale ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.

Azure Portal

1. Na webu Azure Portal vyhledejte svůj účet úložiště pomocí hlavního panelu hledání nebo levé navigace.

2. Na stránce přehledu účtu úložiště v nabídce vlevo vyberte Řízení přístupu (IAM ).

3. Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.

4. V horní nabídce vyberte + Přidat a potom přidejte přiřazení role z výsledné rozevírací nabídky.

   

5. Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte Přispěvatel dat objektů blob služby Storage a vyberte odpovídající výsledek a pak zvolte Další.

6. V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.

7. V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .

8. Vyberte Zkontrolovat a přiřadit přejděte na poslední stránku a pak proces dokončete opětovnou kontrolou a přiřazením .

Azure CLI

Pokud chcete přiřadit roli na úrovni prostředku pomocí Azure CLI, musíte nejprve pomocí příkazu načíst ID az storage account show prostředku. Výstupní vlastnosti můžete filtrovat pomocí parametru --query .

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

Zkopírujte výstup Id z předchozího příkazu. Role pak můžete přiřadit příkazem az role v Azure CLI.

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

PowerShell

Pokud chcete přiřadit roli na úrovni prostředku pomocí Azure PowerShellu, musíte nejprve pomocí příkazu načíst ID Get-AzResource prostředku.

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

Id Zkopírujte hodnotu z předchozího výstupu příkazu. Role pak můžete přiřadit pomocí příkazu New-AzRoleAssignment v PowerShellu.

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

Přihlášení a připojení kódu aplikace k Azure pomocí DefaultAzureCredential

Přístup k datům v účtu úložiště můžete autorizovat pomocí následujícího postupu:

1. Ujistěte se, že jste ověřeni pomocí stejného účtu Microsoft Entra, ke kterému jste přiřadili roli k účtu úložiště. Ověřování můžete provést prostřednictvím Azure CLI. Přihlaste se k Azure prostřednictvím Azure CLI pomocí následujícího příkazu:

   az login
   

2. Chcete-li použítDefaultAzureCredential, ujistěte se, že je nainstalovaný balíček azure-identity-cpp, a je přidán následující#include:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Přidejte tento kód na konec .main() Když se kód spustí na místní pracovní stanici, DefaultAzureCredential použije přihlašovací údaje pro vývojáře pro Azure CLI k ověření v 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. Nezapomeňte aktualizovat název účtu úložiště v identifikátoru URI objektu BlobServiceClient . Název účtu úložiště najdete na stránce přehledu webu Azure Portal.

   

   Poznámka:

   Při použití sady C++ SDK v produkčním prostředí se doporučuje povolit jenom přihlašovací údaje, které znáte, že vaše aplikace bude používat. Místo použití DefaultAzureCredentialbyste měli autorizovat konkrétní typ přihlašovacích údajů nebo použít ChainedTokenCredential s podporovanými přihlašovacími údaji.

Připojovací řetězec

Připojovací řetězec zahrnuje přístupový klíč účtu úložiště a používá ho k autorizaci požadavků. Vždy buďte opatrní, abyste klíče nikdy nezpřístupnili v nezabezpečeném umístění.

Poznámka:

Pokud chcete autorizovat přístup k datům pomocí přístupového klíče účtu úložiště, budete potřebovat oprávnění pro následující akci Azure RBAC: Microsoft.Storage/storageAccounts/listkeys/action. Nejméně privilegovaná předdefinovaná role s oprávněními pro tuto akci je Čtenář a Přístup k datům, ale každá role, která zahrnuje tuto akci, bude fungovat.

Azure Portal

1. Přihlaste se k portálu Azure.

2. Vyhledejte svůj účet úložiště.

3. V podokně nabídek účtu úložiště v části Zabezpečení a sítě vyberte Přístupové klíče. Tady můžete zobrazit přístupové klíče účtu a kompletní připojovací řetězec pro každý klíč.

4. V podokně Přístupové klíče vyberte Zobrazit klíče.

5. V části klíč1 vyhledejte hodnotu řetězce Připojení ion. Výběrem ikony Kopírovat do schránky zkopírujte připojovací řetězec. Hodnotu připojovací řetězec přidáte do proměnné prostředí v další části.

   

Azure CLI

Pomocí příkazu az storage account show-connection-string můžete zobrazit připojovací řetězec vašeho účtu úložiště.

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

PowerShell

Pomocí příkazů Get-AzStorageAccount a Get-AzStorageAccount a Get-AzStorageAccountKey můžete sestavit připojovací řetězec pomocí PowerShellu.

$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'

Konfigurace připojovacího řetězce úložiště

Po zkopírování připojovací řetězec ji zapište do nové proměnné prostředí na místním počítači, na kterém běží aplikace. Proměnnou prostředí nastavíte tak, že otevřete okno konzoly a budete postupovat podle pokynů pro váš operační systém. Nahraďte <yourconnectionstring> skutečnými připojovací řetězec.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Po přidání proměnné prostředí ve Windows musíte spustit novou instanci příkazového okna.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Následující příklad kódu načte připojovací řetězec pro účet úložiště z dříve vytvořené proměnné prostředí a používá připojovací řetězec k vytvoření objektu klienta služby.

Přidejte tento kód na konec 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);

Důležité

Přístupový klíč účtu by se měl používat s opatrností. Pokud dojde ke ztrátě nebo náhodnému umístění přístupového klíče k účtu do nezabezpečeného umístění, může být vaše služba zranitelná. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential poskytuje vylepšené funkce a výhody zabezpečení a je doporučeným přístupem ke správě autorizace služeb Azure.

Vytvoření kontejneru

Rozhodněte se o názvu nového kontejneru. Pak vytvořte instanci BlobContainerClient kontejneru a vytvořte ji.

Důležité

Názvy kontejnerů musí být malými písmeny. Další informace o pojmenování kontejnerů a objektů blob najdete v tématu Názvy kontejnerů, objektů blob a metadat a odkazování na ně.

Přidejte tento kód na konec 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();

Nahrání objektů blob do kontejneru

Následující fragment kódu:

1. Deklaruje řetězec obsahující "Hello Azure!".
2. Získá odkaz na BlockBlobClient objekt volání GetBlockBlobClient v kontejneru oddílu Vytvořit kontejner .
3. Nahraje řetězec do objektu blob voláním funkce UploadFrom . Tato funkce vytvoří objekt blob, pokud ještě neexistuje, nebo ho aktualizuje, pokud ano.

Přidejte tento kód na konec 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));

Seznam objektů blob v kontejneru

Vypište objekty blob v kontejneru voláním funkce ListBlobs . Do kontejneru byl přidán pouze jeden objekt blob, takže operace vrátí pouze tento objekt blob.

Přidejte tento kód na konec main():

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

Stáhnout objekty blob

Získejte vlastnosti nahraného objektu blob. Potom deklarujte a změňte velikost nového std::vector<uint8_t> objektu pomocí vlastností nahraného objektu blob. Stáhněte dříve vytvořený objekt blob do nového std::vector<uint8_t> objektu voláním funkce DownloadTo v základní třídě BlobClient . Nakonec zobrazte stažená data objektů blob.

Přidejte tento kód na konec 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;

Odstranění objektu blob

Následující kód odstraní objekt blob z kontejneru Azure Blob Storage voláním funkce BlobClient.Delete .

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

Odstranění kontejneru

Následující kód vyčistí prostředky, které aplikace vytvořila odstraněním celého kontejneru pomocí BlobContainerClient.Odstranit.

Přidejte tento kód na konec main():

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

Spuštění kódu

Tato aplikace vytvoří kontejner a nahraje textový soubor do služby Azure Blob Storage. Příklad pak vypíše objekty blob v kontejneru, stáhne soubor a zobrazí obsah souboru. Aplikace nakonec odstraní objekt blob a kontejner.

Výstup aplikace je podobný následujícímu příkladu:

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

Další kroky

V tomto rychlém startu jste zjistili, jak pomocí jazyka C++ nahrát, stáhnout a vypsat objekty blob. Dozvěděli jste se také, jak vytvořit a odstranit kontejner Azure Blob Storage.

Pokud chcete zobrazit ukázku služby C++ Blob Storage, pokračujte následujícími postupy:

Ukázky klientské knihovny azure Blob Storage pro C++