Quickstart: Azure Blob Storage-clientbibliotheek voor C++

Ga aan de slag met de Azure Blob Storage-clientbibliotheek voor C++. Azure Blob Storage is de oplossing voor opslag van objecten in de cloud van Microsoft. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

| Broncodevoorbeelden van API-referentiedocumentatiebibliotheek | | |

Vereisten

• Azure-abonnement: u kunt een gratis abonnement nemen
• Azure Storage-account: maak een opslagaccount
• C++ compiler
• CMake
• vcpkg - C- en C++-pakketbeheer

Instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Blob Storage-clientbibliotheek voor C++. De eenvoudigste manier om de Azure SDK voor C++ te verkrijgen, is door pakketbeheer vcpkg te gebruiken.

De pakketten installeren

Gebruik de vcpkg install opdracht om de Azure Blob Storage-bibliotheek voor C++ en de benodigde afhankelijkheden te installeren:

vcpkg.exe install azure-storage-blobs-cpp

De Azure Identity-bibliotheek is nodig voor verbindingen zonder wachtwoord met Azure-services:

vcpkg.exe install azure-identity-cpp

Zie de Leesmij voor Azure SDK voor C++ voor meer informatie over het instellen van projecten en het werken met de Azure SDK voor C++.

Het project maken

Maak in Visual Studio een nieuwe C++-consoletoepassing voor Windows met de naam BlobQuickstart.

Objectmodel

Azure Blob Storage is geoptimaliseerd voor het opslaan van grote hoeveelheden ongestructureerde gegevens. Ongestructureerde gegevens zijn gegevens die niet voldoen aan een bepaald gegevensmodel of bepaalde definitie, zoals tekst of binaire gegevens. Er zijn drie typen resources voor Blob Storage:

• Het opslagaccount
• Een container in het opslagaccount
• Een blob in de container

Het volgende diagram geeft de relatie tussen deze resources weer.

Gebruik deze C++-klassen om te communiceren met deze resources:

• BlobServiceClient: Met de BlobServiceClient klasse kunt u Azure Storage-resources en blobcontainers bewerken.
• BlobContainerClient: Met de BlobContainerClient klasse kunt u Azure Storage-containers en hun blobs bewerken.
• BlobClient: Met de BlobClient klasse kunt u Azure Storage-blobs bewerken. Het is de basisklasse voor alle gespecialiseerde blob-klassen.
• BlockBlobClient: Met de BlockBlobClient klasse kunt u blok-blobs van Azure Storage bewerken.

Codevoorbeelden

Deze voorbeeldcodefragmenten laten zien hoe u de volgende taken kunt uitvoeren met de Azure Blob Storage-clientbibliotheek voor C++:

• Include-bestanden toevoegen
• Verifiëren bij Azure en toegang tot blobgegevens autoriseren
• Een container maken
• Blobs uploaden naar een container
• De blobs in een container weergeven
• Blobs downloaden
• Container verwijderen

Include-bestanden toevoegen

Ga als volgt te werk vanuit de projectmap:

1. Open het oplossingsbestand BlobQuickstart.sln in Visual Studio
2. Open in Visual Studio het bronbestand BlobQuickstart.cpp
3. Alle code in main verwijderen die automatisch is gegenereerd
4. Toevoegen #include en using namespace instructies

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

Verifiëren bij Azure en toegang tot blobgegevens autoriseren

Toepassingsaanvragen voor Azure Blob Storage moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van verbindingen zonder wachtwoorden met Azure-services in uw code, inclusief Blob Storage.

U kunt aanvragen voor Azure Blob Storage ook autoriseren met behulp van de toegangssleutel voor het account. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om de toegangssleutel nooit beschikbaar te maken op een onbeveiligde locatie. Iedereen met de toegangssleutel kan aanvragen voor het opslagaccount autoriseren en heeft effectief toegang tot alle gegevens. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken. Beide opties worden in het volgende voorbeeld gedemonstreerd.

Wachtwoordloos (aanbevolen)

De Azure Identity-bibliotheek biedt verificatieondersteuning voor Microsoft Entra-token in de Azure SDK. Het biedt een reeks TokenCredential implementaties die kunnen worden gebruikt om Azure SDK-clients te bouwen die ondersteuning bieden voor Microsoft Entra-tokenverificatie. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt.

Rollen toewijzen aan uw Microsoft Entra-gebruikersaccount

Zorg er bij het lokaal ontwikkelen voor dat het gebruikersaccount dat toegang heeft tot blobgegevens over de juiste machtigingen beschikt. U hebt Inzender voor Opslagblobgegevens nodig om blobgegevens te lezen en schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Gebruikerstoegang Beheer istrator of een andere rol met de actie Microsoft.Authorization/roleAssignments/write toegewezen krijgen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de overzichtspagina van het bereik.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Inzender voor opslagblobgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot blobgegevens in uw opslagaccount.

Belangrijk

In de meeste gevallen duurt het een of twee minuten voordat de roltoewijzing is doorgegeven in Azure, maar in zeldzame gevallen kan het maximaal acht minuten duren. Als u verificatiefouten ontvangt wanneer u de code voor het eerst uitvoert, wacht u even en probeert u het opnieuw.

Azure-portal

1. Zoek uw opslagaccount in Azure Portal met behulp van de hoofdzoekbalk of linkernavigatiebalk.

2. Selecteer op de overzichtspagina van het opslagaccount toegangsbeheer (IAM) in het menu aan de linkerkant.

3. Selecteer op de pagina Toegangsbeheer (IAM) het tabblad Roltoewijzingen .

4. Selecteer + Toevoegen in het bovenste menu en voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.

   

5. Gebruik het zoekvak om de resultaten te filteren op de gewenste rol. Zoek in dit voorbeeld naar Inzender voor Opslagblobgegevens en selecteer het overeenkomende resultaat en kies vervolgens Volgende.

6. Selecteer onder Toegang toewijzen de optie Gebruiker, groep of service-principal en kies vervolgens + Leden selecteren.

7. Zoek in het dialoogvenster naar uw Microsoft Entra-gebruikersnaam (meestal uw user@domain e-mailadres) en kies Vervolgens onderaan het dialoogvenster Selecteren .

8. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

Azure-CLI

Als u een rol wilt toewijzen op resourceniveau met behulp van de Azure CLI, moet u eerst de resource-id ophalen met behulp van de az storage account show opdracht. U kunt de uitvoereigenschappen filteren met behulp van de --query parameter.

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

Kopieer de uitvoer Id van de voorgaande opdracht. Vervolgens kunt u rollen toewijzen met behulp van de az-rolopdracht van de Azure CLI.

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

PowerShell

Als u een rol wilt toewijzen op resourceniveau met behulp van Azure PowerShell, moet u eerst de resource-id ophalen met behulp van de Get-AzResource opdracht.

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

Kopieer de Id waarde uit de voorgaande opdrachtuitvoer. Vervolgens kunt u rollen toewijzen met behulp van de opdracht New-AzRoleAssignment in PowerShell.

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

Meld u aan en verbind uw app-code met Azure met behulp van DefaultAzureCredential

U kunt toegang tot gegevens in uw opslagaccount autoriseren met behulp van de volgende stappen:

1. Zorg ervoor dat u bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen in uw opslagaccount. U kunt verifiëren via Azure CLI. Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

   az login
   

2. Als u het pakket azure-identity-cpp wilt gebruiken DefaultAzureCredential, moet u ervoor zorgen dat het pakket azure-identity-cpp is geïnstalleerd en wordt het volgende #include toegevoegd:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Voeg deze code toe aan het einde van main(). Wanneer de code wordt uitgevoerd op uw lokale werkstation, DefaultAzureCredential gebruikt u de referenties van de ontwikkelaar voor Azure CLI om te verifiëren bij 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. Zorg ervoor dat u de naam van het opslagaccount bijwerkt in de URI van uw BlobServiceClient object. De naam van het opslagaccount vindt u op de overzichtspagina van Azure Portal.

   

   Notitie

   Wanneer u de C++ SDK in een productieomgeving gebruikt, is het raadzaam om alleen referenties in te schakelen die u kent dat uw toepassing wordt gebruikt. In plaats van te gebruiken DefaultAzureCredential, moet u autoriseren met een specifiek referentietype of met behulp van ChainedTokenCredential de ondersteunde referenties.

Verbindingsreeks

Een verbindingsreeks bevat de toegangssleutel voor het opslagaccount en gebruikt deze om aanvragen te autoriseren. Wees altijd voorzichtig om de sleutels nooit zichtbaar te maken op een onbeveiligde locatie.

Notitie

Als u gegevenstoegang wilt autoriseren met de toegangssleutel voor het opslagaccount, hebt u machtigingen nodig voor de volgende Azure RBAC-actie: Microsoft.Storage/storageAccounts/listkeys/action. De minst bevoorrechte ingebouwde rol met machtigingen voor deze actie is Lezer en Gegevenstoegang, maar elke rol die deze actie omvat, werkt.

Azure-portal

1. Meld u aan bij de Azure-portal.

2. Zoek uw opslagaccount.

3. Selecteer toegangssleutels in het menuvenster van het opslagaccount onder Beveiliging en netwerken. Hier kunt u de toegangssleutels van het account en de volledige verbindingsreeks voor elke sleutel bekijken.

4. Selecteer Sleutels weergeven in het deelvenster Toegangssleutels.

5. Zoek in de sectie sleutel1 de tekenreekswaarde Verbinding maken. Selecteer het pictogram Kopiëren naar klembord om de verbindingsreeks te kopiëren. In de volgende sectie voegt u de verbindingsreeks waarde toe aan een omgevingsvariabele.

   

Azure-CLI

U kunt de verbindingsreeks voor uw opslagaccount zien met behulp van de opdracht az storage account show-connection-string.

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

PowerShell

U kunt een verbindingsreeks samenstellen met PowerShell met behulp van de opdrachten Get-AzStorageAccount en Get-AzStorageAccountKey.

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

De opslagverbindingsreeks configureren

Nadat u de verbindingsreeks hebt gekopieerd, schrijft u deze naar een nieuwe omgevingsvariabele op de lokale computer waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, opent u een consolevenster en volgt u de aanwijzingen voor uw besturingssysteem. Vervang <yourconnectionstring> door de feitelijke verbindingsreeks.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Nadat u de omgevingsvariabele in Windows hebt toegevoegd, moet u een nieuw exemplaar van het opdrachtvenster starten.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

In het volgende codevoorbeeld wordt de verbindingsreeks voor het opslagaccount opgehaald uit de omgevingsvariabele die u eerder hebt gemaakt en wordt de verbindingsreeks gebruikt om een serviceclientobject te maken.

Voeg deze code toe aan het einde van 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);

Belangrijk

De toegangssleutel voor het account moet voorzichtig worden gebruikt. Als uw accounttoegangssleutel verloren gaat of per ongeluk op een onveilige locatie is geplaatst, kan uw service kwetsbaar worden. Iedereen met de toegangssleutel kan aanvragen voor het opslagaccount autoriseren en heeft effectief toegang tot alle gegevens. DefaultAzureCredential biedt verbeterde beveiligingsfuncties en voordelen en is de aanbevolen benadering voor het beheren van autorisatie voor Azure-services.

Een container maken

Verzin een naam voor de nieuwe container. Maak vervolgens een exemplaar van BlobContainerClient en maak de container.

Belangrijk

Containernamen moeten uit kleine letters bestaan. Zie Containers, blobs en metagegevens een naam geven en hiernaar verwijderen voor meer informatie over de naamgeving van containers en blobs.

Voeg deze code toe aan het einde van 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();

Blobs uploaden naar een container

Het volgende codefragment:

1. Declareert een tekenreeks met 'Hallo Azure!'
2. Hiermee wordt een verwijzing opgehaald naar een object BlockBlobClient door het aanroepen van GetBlockBlobClient op de container vanuit de sectie Een container maken.
3. Uploadt de tekenreeks naar de blob door de functie UploadFrom aan te roepen. Met deze functie wordt de blob gemaakt als deze nog niet bestaat, of wordt deze bijgewerkt als dat wel het geval is.

Voeg deze code toe aan het einde van 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));

Blobs in een container vermelden

Geef de blobs in de container weer door de functie ListBlobs aan te roepen. Er is slechts één blob aan de container toegevoegd, dus de bewerking retourneert alleen die blob.

Voeg deze code toe aan het einde van main():

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

Blobs downloaden

De eigenschappen van de geüploade blob ophalen. Vervolgens declareert en wijzigt u het formaat van een nieuw std::vector<uint8_t>-object met behulp van de eigenschappen van de geüploade blob. Download de eerder gemaakte blob naar het nieuwe std::vector<uint8_t> object door de functie DownloadTo aan te roepen in de blobClient-basisklasse . Ten slotte geeft u de gedownloade blob-gegevens weer.

Voeg deze code toe aan het einde van 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;

Een blob verwijderen

Met de volgende code wordt de blob uit de Azure Blob Storage-container verwijderd door de functie BlobClient.Delete aan te roepen.

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

Een container verwijderen

Met de volgende code worden de resources opgeschoond die de app heeft gemaakt door de hele container te verwijderen met behulp van BlobContainerClient.Verwijderen.

Voeg deze code toe aan het einde van main():

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

De code uitvoeren

Met deze app maakt u een container en uploadt u een tekstbestand naar Azure Blob Storage. Vervolgens wordt een lijst gemaakt van de blobs in de container, wordt het bestand gedownload en wordt de bestandsinhoud weergegeven. Ten slotte verwijdert de app de blob en de container.

De uitvoer van de app lijkt op die in het volgende voorbeeld:

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

Volgende stappen

In deze quickstart hebt u geleerd hoe u blobs kunt uploaden, downloaden en er een lijst van kunt maken met behulp van C++. U hebt ook geleerd hoe u een Azure Blob Storage-container maakt en verwijdert.

Als u een voorbeeld wilt zien van Blob Storage voor C++, ga dan naar:

Azure Blob Storage-clientbibliotheek voor C++-voorbeelden