Rövid útmutató: Az Azure Blob Storage C++ ügyfélkódtára

Ismerkedés az Azure Blob Storage C++-hoz készült ügyfélkódtárával. Az Azure Blob Storage a Microsoft objektumtárolási megoldása a felhőhöz. Az alábbi lépések végrehajtásával telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

| API-referenciadokumentáció Kódtár forráskódminták | | |

Előfeltételek

• Azure-előfizetés – hozzon létre egyet ingyenesen
• Azure Storage-fiók – tárfiók létrehozása
• C++ fordító
• CMake
• vcpkg – C és C++ csomagkezelő

Beállítás

Ez a szakasz végigvezeti egy projekt előkészítésén az Azure Blob Storage C++-hoz készült ügyfélkódtárával való együttműködésre. A C++ azure SDK beszerzésének legegyszerűbb módja a vcpkg csomagkezelő használata.

A csomagok telepítése

vcpkg install A parancs használatával telepítse az Azure Blob Storage C++ kódtárát és a szükséges függőségeket:

vcpkg.exe install azure-storage-blobs-cpp

Az Azure Identity-kódtárra az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatokhoz van szükség:

vcpkg.exe install azure-identity-cpp

A projekt beállításával és a C++-hoz készült Azure SDK-val való munkával kapcsolatos további információkért tekintse meg az Azure SDK for C++ olvasási útmutatóját.

A projekt létrehozása

A Visual Studióban hozzon létre egy új C++ konzolalkalmazást a Windowshoz BlobQuickstart néven.

Objektummodell

Az Azure Blob Storage nagy mennyiségű strukturálatlan adat tárolására van optimalizálva. A strukturálatlan adatok olyan adatok, amelyek nem követnek egy adott adatmodellt vagy -definíciót, például szöveges vagy bináris adatok. A Blob Storage háromféle erőforrást kínál:

• A tárfiók
• Tároló a tárfiókban
• Blob a tárolóban

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

Az alábbi C++ osztályokkal kezelheti ezeket az erőforrásokat:

• BlobServiceClient: Az BlobServiceClient osztály lehetővé teszi az Azure Storage-erőforrások és blobtárolók manipulálására.
• BlobContainerClient: Az BlobContainerClient osztály lehetővé teszi az Azure Storage-tárolók és a blobok manipulálására.
• BlobClient: Az BlobClient osztály lehetővé teszi az Azure Storage-blobok manipulálására. Ez az összes speciális blobosztály alaposztálya.
• BlockBlobClient: Az BlockBlobClient osztály lehetővé teszi az Azure Storage blokkblobok manipulálására.

Kódpéldák

Ezek a példakódrészletek bemutatják, hogyan végezheti el a következő feladatokat az Azure Blob Storage C++-hoz készült ügyfélkódtárával:

• Belefoglalási fájlok hozzáadása
• Hitelesítés az Azure-ban és a blobadatokhoz való hozzáférés engedélyezése
• Tároló létrehozása
• Blobok feltöltése tárolóba
• A tárolóban lévő blobok listázása
• Blobok letöltése
• Tároló törlése

Belefoglalási fájlok hozzáadása

A projektkönyvtárból:

1. A BlobQuickstart.sln megoldásfájl megnyitása a Visual Studióban
2. Nyissa meg a BlobQuickstart.cpp forrásfájlt a Visual Studióban
3. Automatikusan létrehozott kód main eltávolítása
4. Hozzáadás #include és using namespace utasítások

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

Hitelesítés az Azure-ban és a blobadatokhoz való hozzáférés engedélyezése

Az Azure Blob Storage-ba irányuló alkalmazáskéréseket engedélyezni kell. DefaultAzureCredential Az Azure Identity-ügyfélkódtár által biztosított osztály használata ajánlott módszer az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatok implementálásához a kódban, beleértve a Blob Storage-t is.

Az Azure Blob Storage-ra irányuló kéréseket a fiók hozzáférési kulcsával is engedélyezheti. Ezt a megközelítést azonban körültekintően kell alkalmazni. A fejlesztőknek szorgalmasnak kell lenniük, hogy soha ne tegyék elérhetővé a hozzáférési kulcsot nem biztonságos helyen. Bárki, aki rendelkezik a hozzáférési kulccsal, engedélyezheti a tárfiókra irányuló kérelmeket, és hatékonyan hozzáférhet az összes adathoz. DefaultAzureCredential továbbfejlesztett felügyeleti és biztonsági előnyöket kínál a fiókkulcson keresztül a jelszó nélküli hitelesítés engedélyezéséhez. Az alábbi példában mindkét lehetőség látható.

Jelszó nélküli (ajánlott)

Az Azure Identity-kódtár Microsoft Entra-jogkivonat-hitelesítést biztosít az Azure SDK-ban. Számos olyan implementációt TokenCredential biztosít, amelyek a Microsoft Entra jogkivonat-hitelesítést támogató Azure SDK-ügyfelek létrehozásához használhatók. DefaultAzureCredential több hitelesítési módszert támogat, és meghatározza, hogy melyik metódust kell használni futásidőben.

Szerepkörök hozzárendelése a Microsoft Entra felhasználói fiókjához

Helyi fejlesztéskor győződjön meg arról, hogy a blobadatokhoz hozzáférő felhasználói fiók rendelkezik a megfelelő engedélyekkel. A blobadatok olvasásához és írásához tárolóblobadatok közreműködője szükséges. A szerepkör hozzárendeléséhez hozzá kell rendelnie a Felhasználói hozzáférés Rendszergazda istrator szerepkört, vagy egy másik szerepkört, amely tartalmazza a Microsoft.Authorization/roleAssignments/write műveletet. Azure RBAC-szerepköröket rendelhet egy felhasználóhoz az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával. A szerepkör-hozzárendelések elérhető hatóköreiről a hatókör áttekintési oldalán tudhat meg többet.

Ebben a forgatókönyvben engedélyeket rendel hozzá a felhasználói fiókjához, amely a tárfiókra terjed ki, hogy kövesse a minimális jogosultság elvét. Ez a gyakorlat csak a minimálisan szükséges engedélyeket biztosítja a felhasználóknak, és biztonságosabb éles környezeteket hoz létre.

Az alábbi példa a Storage Blob Data Contributor szerepkört rendeli hozzá a felhasználói fiókjához, amely olvasási és írási hozzáférést biztosít a tárfiók blobadataihoz.

Fontos

A szerepkör-hozzárendelés propagálása a legtöbb esetben egy-két percet vesz igénybe az Azure-ban, de ritkán akár nyolc percet is igénybe vehet. Ha hitelesítési hibákat kap a kód első futtatásakor, várjon néhány percet, és próbálkozzon újra.

Azure Portal

1. Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.

2. A tárfiók áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget a bal oldali menüben.

3. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.

4. Válassza a +Hozzáadás lehetőséget a felső menüből, majd a szerepkör-hozzárendelés hozzáadása lehetőséget az eredményül kapott legördülő menüből.

   

5. A keresőmezővel szűrheti az eredményeket a kívánt szerepkörre. Ebben a példában keresse meg a Storage Blob-adatszolgáltatót, és válassza ki a megfelelő eredményt, majd válassza a Tovább gombot.

6. A Hozzáférés hozzárendelése területen válassza a Felhasználó, csoport vagy szolgáltatásnév lehetőséget, majd válassza a + Tagok kijelölése lehetőséget.

7. A párbeszédpanelen keresse meg a Microsoft Entra-felhasználónevet (általában a user@domain e-mail-címét), majd válassza a Párbeszédpanel alján található Kiválasztás lehetőséget.

8. Válassza a Véleményezés + hozzárendelés lehetőséget a végső lapra való ugráshoz, majd a folyamat befejezéséhez a Véleményezés + hozzárendelés lehetőséget.

Azure CLI

Ha az Azure CLI használatával szeretne szerepkört hozzárendelni az erőforrásszinthez, először le kell kérnie az erőforrás-azonosítót a az storage account show parancs használatával. A kimeneti tulajdonságokat a --query paraméterrel szűrheti.

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

Másolja ki a kimenetet Id az előző parancsból. Ezután az Azure CLI szerepkör-parancsával rendelhet hozzá szerepköröket.

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

PowerShell

Ha az Azure PowerShell használatával szeretne szerepkört hozzárendelni az erőforrásszinthez, először le kell kérnie az erőforrás-azonosítót a Get-AzResource paranccsal.

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

Másolja ki az értéket az Id előző parancskimenetből. Ezután a New-AzRoleAssignment paranccsal rendelhet hozzá szerepköröket a PowerShellben.

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

Jelentkezzen be, és csatlakoztassa az alkalmazáskódot az Azure-hoz a DefaultAzureCredential használatával

A tárfiókban lévő adatokhoz való hozzáférést az alábbi lépések végrehajtásával engedélyezheti:

1. Győződjön meg arról, hogy ugyanazzal a Microsoft Entra-fiókkal van hitelesítve, amelyhez a szerepkört hozzárendelte a tárfiókban. Hitelesítést az Azure CLI-vel végezhet. Jelentkezzen be az Azure-ba az Azure CLI-vel a következő paranccsal:

   az login
   

2. A használathoz DefaultAzureCredentialgyőződjön meg arról, hogy az azure-identity-cpp csomag telepítve van, és a következőt #include adja hozzá:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Adja hozzá ezt a kódot a végéhez main(). Amikor a kód a helyi munkaállomáson fut, DefaultAzureCredential az Azure CLI fejlesztői hitelesítő adataival hitelesítheti magát az Azure-ban.

   // 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. Mindenképpen frissítse a tárfiók nevét az objektum URI-jában BlobServiceClient . A tárfiók neve az Azure Portal áttekintési oldalán található.

   

   Megjegyzés:

   Ha éles környezetben használja a C++ SDK-t, javasoljuk, hogy csak olyan hitelesítő adatokat engedélyezzen, amelyekről tudja, hogy az alkalmazás használni fogja. A használat DefaultAzureCredentialhelyett engedélyeznie kell egy adott hitelesítő adattípus használatát, vagy a támogatott hitelesítő adatokkal ChainedTokenCredential .

Kapcsolati sztring

A kapcsolati sztring tartalmazza a tárfiók hozzáférési kulcsát, és a kérések engedélyezésére használja. Mindig legyen óvatos, hogy soha ne tegye elérhetővé a kulcsokat nem biztonságos helyen.

Megjegyzés:

A tárfiók hozzáférési kulcsával való adathozzáférés engedélyezéséhez a következő Azure RBAC-művelet engedélyére lesz szüksége: Microsoft.Storage/storageAccounts/listkeys/action. A művelet engedélyeivel rendelkező legkevésbé kiemelt beépített szerepkör az Olvasó és az Adathozzáférés, de minden olyan szerepkör, amely tartalmazza ezt a műveletet, működni fog.

Azure Portal

1. Jelentkezzen be az Azure Portalra.

2. Keresse meg a Storage-fiókját.

3. A Tárfiók menüpanel Biztonság + hálózatkezelés területén válassza az Access-kulcsokat. Itt megtekintheti a fiók hozzáférési kulcsait és az egyes kulcsok teljes kapcsolati sztring.

4. Az Access-kulcsok panelen válassza a Kulcsok megjelenítése lehetőséget.

5. A kulcs1 szakaszban keresse meg a Csatlakozás ion sztring értékét. Válassza a Másolás vágólapra ikont a kapcsolati sztring másolásához. A kapcsolati sztring értéket egy környezeti változóhoz fogja hozzáadni a következő szakaszban.

   

Azure CLI

A tárfiókhoz tartozó kapcsolati sztring az az storage account show-connection-string paranccsal tekintheti meg.

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

PowerShell

A Get-AzStorageAccount és a Get-AzStorageAccountKey parancsokkal összeállíthat egy kapcsolati sztring a PowerShell használatával.

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

A tárolási kapcsolati sztring konfigurálása

A kapcsolati sztring másolása után írja be egy új környezeti változóba az alkalmazást futtató helyi gépen. A környezeti változó megadásához nyisson meg egy konzolablakot, és kövesse az operációs rendszerének megfelelő utasításokat. Cserélje le <yourconnectionstring> a tényleges kapcsolati sztring.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Miután hozzáadta a környezeti változót a Windowsban, el kell indítania a parancsablak új példányát.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Az alábbi példakód lekéri a tárfiók kapcsolati sztring a korábban létrehozott környezeti változóból, és a kapcsolati sztring használatával hoz létre egy szolgáltatásügyfél-objektumot.

Adja hozzá ezt a kódot a következő végéhez 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);

Fontos

A fiók hozzáférési kulcsát körültekintően kell használni. Ha a fiók hozzáférési kulcsa elveszett vagy véletlenül nem biztonságos helyre került, a szolgáltatás sebezhetővé válhat. Bárki, aki rendelkezik a hozzáférési kulccsal, engedélyezheti a tárfiókra irányuló kérelmeket, és hatékonyan hozzáférhet az összes adathoz. DefaultAzureCredential továbbfejlesztett biztonsági funkciókat és előnyöket biztosít, és az Azure-szolgáltatásokhoz való engedélyezés kezelésének ajánlott megközelítése.

Tároló létrehozása

Döntse el az új tároló nevét. Ezután hozzon létre egy példányt BlobContainerClient , és hozza létre a tárolót.

Fontos

A tárolók nevei csak kisbetűket tartalmazhatnak. A tárolók és blobok elnevezésével kapcsolatos további információkért lásd a tárolók, blobok és metaadatok elnevezését és hivatkozását.

Adja hozzá ezt a kódot a következő végéhez 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();

Blobok feltöltése tárolóba

A következő kódrészlet:

1. Deklarál egy "Hello Azure!" sztringet
2. Egy BlockBlobClient objektumra mutató hivatkozás lekéréséhez hívja meg a GetBlockBlobClientet a tárolón a Tároló létrehozása szakaszból.
3. Az UploadFrom függvény meghívásával feltölti a sztringet a blobba. Ez a függvény létrehozza a blobot, ha még nem létezik, vagy frissíti, ha igen.

Adja hozzá ezt a kódot a következő végéhez 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));

Tárolóban lévő blobok kilistázása

Sorolja fel a tárolóban lévő blobokat a ListBlobs függvény meghívásával. A tárolóhoz csak egy blob lett hozzáadva, így a művelet csak azt a blobot adja vissza.

Adja hozzá ezt a kódot a következő végéhez main():

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

Blobok letöltése

A feltöltött blob tulajdonságainak lekérése. Ezután deklaráljon és méretezze át az új std::vector<uint8_t> objektumot a feltöltött blob tulajdonságaival. Töltse le a korábban létrehozott blobot az új std::vector<uint8_t> objektumba a BlobClient alaposztály DownloadTo függvényének meghívásával. Végül jelenítse meg a letöltött blobadatokat.

Adja hozzá ezt a kódot a következő végéhez 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 törlése

Az alábbi kód a BlobClient.Delete függvény meghívásával törli a blobot az Azure Blob Storage-tárolóból.

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

Tároló törlése

Az alábbi kód megtisztítja az alkalmazás által létrehozott erőforrásokat, és törli a teljes tárolót a BlobContainerClient használatával .Törlés.

Adja hozzá ezt a kódot a következő végéhez main():

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

A kód futtatása

Ez az alkalmazás létrehoz egy tárolót, és feltölt egy szöveges fájlt az Azure Blob Storage-ba. A példa ezután felsorolja a tárolóban lévő blobokat, letölti a fájlt, és megjeleníti a fájl tartalmát. Végül az alkalmazás törli a blobot és a tárolót.

Az alkalmazás kimenete a következő példához hasonló:

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

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan tölthet fel, tölthet le és listázhat blobokat a C++ használatával. Azt is megtanulta, hogyan hozhat létre és törölhet Egy Azure Blob Storage-tárolót.

C++ Blob Storage-minta megtekintéséhez folytassa a következővel:

Azure Blob Storage ügyfélkódtár C++ mintákhoz