Schnellstart: Azure Blob Storage-Clientbibliothek für C++

Erfahren Sie etwas über die ersten Schritte mit der Azure Blob Storage-Clientbibliothek für C++. Azure Blob Storage ist die Objektspeicherlösung von Microsoft für die Cloud. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

| API-Referenzdokumentation | Quellcode der Bibliothek | Beispiele |

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Azure Storage-Konto – Erstellen eines Speicherkontos
• C++-Compiler
• CMake
• vcpkg: C- und C++-Paket-Manager

Einrichten

In diesem Abschnitt wird beschrieben, wie ein Projekt zur Verwendung mit der Azure Blob Storage-Clientbibliothek für C++ vorbereitet wird. Die einfachste Möglichkeit, das Azure SDK für C++ zu erwerben, ist die Verwendung des vcpkg-Paket-Managers.

Installieren der Pakete

Verwenden Sie den Befehl vcpkg install, um die Azure Blob Storage-Bibliothek für C++ und die erforderlichen Abhängigkeiten zu installieren:

vcpkg.exe install azure-storage-blobs-cpp

Für kennwortlose Verbindungen mit Azure-Diensten wird die Azure.Identity-Bibliothek benötigt.

vcpkg.exe install azure-identity-cpp

Weitere Informationen zur Projekteinrichtung und zum Arbeiten mit dem Azure SDK für C++ finden Sie in der Infodatei zum Azure SDK für C++.

Erstellen des Projekts

Erstellen Sie in Visual Studio eine neue C++-Konsolenanwendung für Windows mit dem Namen BlobQuickstart.

Objektmodell

Azure Blob Storage ist für die Speicherung großer Mengen unstrukturierter Daten optimiert. Unstrukturierte Daten sind Daten, die keinem bestimmten Datenmodell und keiner bestimmten Definition entsprechen (also beispielsweise Text- oder Binärdaten). Blob Storage bietet drei Typen von Ressourcen:

• Das Speicherkonto
• Einen Container im Speicherkonto
• Ein Blob im Container

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.

Verwenden Sie diese C++-Klassen um mit diesen Ressourcen zu interagieren:

• BlobServiceClient: Die BlobServiceClient-Klasse ermöglicht Ihnen, Azure Storage-Ressourcen und Blobcontainer zu bearbeiten.
• BlobContainerClient: Die BlobContainerClient-Klasse ermöglicht Ihnen, Azure Storage-Container und deren Blobs zu bearbeiten.
• BlobClient: Die BlobClient-Klasse ermöglicht Ihnen, Azure Storage-Blobs zu bearbeiten. Dies ist die Basisklasse für alle spezialisierten Blobklassen.
• BlockBlobClient: Die BlockBlobClient-Klasse ermöglicht es Ihnen, Azure Storage-Blockblobs zu bearbeiten.

Codebeispiele

Mit diesen Beispielcodeausschnitten wird veranschaulicht, wie folgende Vorgänge mit der Azure Blob Storage-Clientbibliothek für C++ durchgeführt werden:

• Hinzufügen von Includedateien
• Authentifizieren bei Azure und Autorisieren des Zugriffs auf Blobdaten
• Container erstellen
• Hochladen von Blobs in einen Container
• Auflisten der Blobs in einem Container
• Herunterladen von Blobs
• Löschen eines Containers

Hinzufügen von Includedateien

Über das Projektverzeichnis:

1. Öffnen Sie in Visual Studio die Projektmappendatei BlobQuickstart.sln.
2. Öffnen Sie in Visual Studio die Quelldatei BlobQuickstart.cpp.
3. Entfernen Sie den Code in main, der automatisch generiert wurde.
4. Hinzufügen von #include- und using namespace-Anweisungen

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

Authentifizieren bei Azure und Autorisieren des Zugriffs auf Blobdaten

Anwendungsanforderungen an Azure Blob Storage müssen autorisiert werden. Die Verwendung der von der Azure Identity-Clientbibliothek bereitgestellten Klasse DefaultAzureCredential ist der empfohlene Ansatz zum Implementieren von kennwortlosen Verbindungen mit Azure-Diensten in Ihrem Code, einschließlich Blob Storage.

Sie können Anforderungen an Azure Blob Storage auch mithilfe des Kontozugriffsschlüssels autorisieren. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass die Zugriffsschlüssel niemals an einem unsicheren Ort offengelegt werden. Jeder, der über den Zugriffsschlüssel verfügt, kann Anforderungen für das Speicherkonto autorisieren und hat somit Zugriff auf alle Daten. DefaultAzureCredential bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um kennwortlose Authentifizierung zu ermöglichen. Beide Optionen werden im folgenden Beispiel veranschaulicht.

Kennwortlos (empfohlen)

Mit der Azure-Identitätsbibliothek wird die Microsoft Entra-Tokenauthentifizierung für das Azure SDK unterstützt. Sie bietet eine Reihe von TokenCredential-Implementierungen, die zum Erstellen von Azure SDK-Clients verwendet werden können, die Microsoft Entra-Tokenauthentifizierung unterstützen. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll.

Zuweisen von Rollen zu Ihrem Microsoft Entra-Benutzerkonto

Stellen Sie bei lokaler Entwicklung sicher, dass das Benutzerkonto, das auf Blobdaten zugreift, über die richtigen Berechtigungen verfügt. Sie benötigen die Berechtigung Mitwirkender an Storage-Blobdaten zum Lesen und Schreiben von Blobdaten. Um sich selbst diese Rolle zuweisen zu können, benötigen Sie die Rolle Benutzerzugriffsadministrator oder eine andere Rolle, die die Aktion Microsoft.Authorization/roleAssignments/write enthält. Sie können einem Benutzer Azure RBAC-Rollen über das Azure-Portal, die Azure CLI oder mit Azure PowerShell zuweisen. Weitere Informationen zu den verfügbaren Bereichen für Rollenzuweisungen finden Sie auf der Seite Bereichsübersicht.

In diesem Szenario weisen Sie Ihrem Benutzerkonto Berechtigungen zu, die auf das Speicherkonto zugeschnitten sind, um dem Prinzip der geringsten Rechte zu folgen. Auf diese Weise erhalten Benutzer nur die erforderlichen Mindestberechtigungen, und es entstehen sicherere Produktionsumgebungen.

Im folgenden Beispiel wird Ihrem Benutzerkonto die Rolle Mitwirkender an Storage-Blobdaten zugewiesen, die sowohl Lese- als auch Schreibzugriff auf Blobdaten in Ihrem Speicherkonto ermöglicht.

Wichtig

In den meisten Fällen dauert es eine oder zwei Minute(n), bis die Rollenzuweisung in Azure weitergegeben wird. In seltenen Fällen kann es aber bis zu acht Minuten dauern. Wenn bei der ersten Ausführung Ihres Codes Authentifizierungsfehler auftreten, warten Sie einige Momente, und versuchen Sie es dann erneut.

Azure portal

1. Suchen Sie im Azure-Portal Ihr Speicherkonto mithilfe der Hauptsuchleiste oder der linken Navigationsleiste.

2. Wählen Sie auf der Übersichtsseite des Speicherkontos im linken Menü die Option Zugriffssteuerung (IAM) aus.

3. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Registerkarte Rollenzuweisungen aus.

4. Wählen Sie im oberen Menü + Hinzufügen und aus dem dann angezeigten Dropdownmenü die Option Rollenzuweisung hinzufügen aus.

   

5. Über das Suchfeld können Sie die Ergebnisse für die gewünschte Rolle filtern. Suchen Sie in diesem Beispiel nach Mitwirkender an Speicherblobdaten, wählen Sie das entsprechende Ergebnis und dann Weiter aus.

6. Wählen Sie unter Zugriff zuweisen zu die Option Benutzer, Gruppe oder Dienstprinzipal und dann die Option + Mitglieder auswählen aus.

7. Suchen Sie im Dialogfeld nach Ihrem Microsoft Entra-Benutzernamen (in der Regel Ihre user@domain-E-Mail-Adresse), und wählen Sie dann unten im Dialogfeld Auswählen aus.

8. Wählen Sie Überprüfen und zuweisen aus, um zur letzten Seite zu gelangen, und wählen Sie erneut Überprüfen und zuweisen aus, um den Vorgang abzuschließen.

Azure-Befehlszeilenschnittstelle

Um eine Rolle auf Ressourcenebene über die Azure CLI zuweisen zu können, müssen Sie zuerst die Ressourcen-ID mithilfe des Befehls az storage account show abrufen. Sie können die Ausgabeeigenschaften mithilfe des Parameters --query filtern.

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

Kopieren Sie die Ausgabe-Id aus dem vorhergehenden Befehl. Dann können Sie Rollen mithilfe des Befehls az role der Azure CLI zuweisen.

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

PowerShell

Um eine Rolle auf Ressourcenebene mithilfe von Azure PowerShell zuweisen zu können, müssen Sie zuerst die Ressourcen-ID mithilfe des Befehls Get-AzResource abrufen.

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

Kopieren Sie den Id-Wert aus der vorhergehenden Befehlsausgabe. Dann können Sie Rollen mithilfe des Befehls New-AzRoleAssignment in PowerShell zuweisen.

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

Anmelden und Verbinden ihres App-Codes mit Azure mithilfe von „DefaultAzureCredential“

Sie können den Zugriff auf Daten in Ihrem Speicherkonto mithilfe der folgenden Schritte autorisieren:

1. Stellen Sie sicher, dass Sie mit demselben Microsoft Entra-Konto authentifiziert sind, dem Sie die Rolle für Ihr Speicherkonto zugewiesen haben. Sie können sich über die Azure CLI authentifizieren. Melden Sie sich mit dem folgenden Befehl über die Azure-Befehlszeilenschnittstelle bei Azure an:

   az login
   

2. Wenn Sie DefaultAzureCredential verwenden möchten, vergewissern Sie sich, dass das Paketazure-identity-cppinstalliert wurde und der folgende #include hinzugefügt wird:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Fügen Sie diesen Code am Ende von main() hinzu. Wenn der Code auf Ihrer lokalen Arbeitsstation ausgeführt wird, verwendet DefaultAzureCredential die Entwickleranmeldeinformationen für die Azure CLI zum Authentifizieren bei 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. Achten Sie darauf, den Namen des Speicherkontos im URI Ihres BlobServiceClient-Objekts zu aktualisieren. Den Name des Speicherkontos finden Sie auf der Übersichtsseite des Azure-Portals.

   

   Hinweis

   Wenn Sie das C++-SDK in einer Produktionsumgebung verwenden, wird empfohlen, nur Anmeldeinformationen zu aktivieren, von denen Sie wissen, dass sie von Ihrer Anwendung verwendet werden. Anstatt DefaultAzureCredential zu verwenden, sollten Sie die Autorisierung mithilfe eines bestimmten Anmeldeinformationstyps oder mithilfe von ChainedTokenCredential mit den unterstützten Anmeldeinformationen durchführen.

Verbindungszeichenfolge

Eine Verbindungszeichenfolge enthält den Zugriffsschlüssel für das Speicherkonto, den sie zum Autorisieren von Anforderungen verwendet. Achten Sie immer darauf, die Schlüssel an einem unsicheren Ort niemals verfügbar zu machen.

Hinweis

Zum Autorisieren des Datenzugriffs mit dem Speicherkontozugriffsschlüssel benötigen Sie Berechtigungen für die folgende Azure RBAC-Aktion: Microsoft.Storage/storageAccounts/listkeys/action. Die integrierte Rolle mit den geringsten Rechten mit Berechtigungen für diese Aktion ist Lese- und Datenzugriff, aber jede Rolle, die diese Aktion umfasst, funktioniert.

Azure portal

1. Melden Sie sich beim Azure-Portal an.

2. Suchen Sie nach Ihrem Speicherkonto.

3. Wählen Sie im Speicherkonto-Menübereich unter Sicherheit + Netzwerkbetrieb die Option Zugriffsschlüssel aus. Hier können Sie die Kontozugriffsschlüssel und die vollständige Verbindungszeichenfolge für jeden Schlüssel anzeigen.

4. Wählen Sie im Bereich Zugriffsschlüssel die Option Schlüssel anzeigen aus.

5. Suchen Sie im Abschnitt key1 nach dem Wert Verbindungszeichenfolge. Wählen Sie das Symbol In Zwischenablage kopieren zum Kopieren der Verbindungszeichenfolge aus. Im nächsten Abschnitt fügen Sie den Wert der Verbindungszeichenfolge in eine Umgebungsvariable ein.

   

Azure-Befehlszeilenschnittstelle

Mithilfe des Befehls az storage account show-connection-string können Sie die Verbindungszeichenfolge für Ihr Speicherkonto anzeigen.

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

PowerShell

Mithilfe der Befehle Get-AzStorageAccount und Get-AzStorageAccountKey können Sie eine Verbindungszeichenfolge mit PowerShell zusammenstellen.

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

Konfigurieren der Speicherverbindungszeichenfolge

Schreiben Sie die Verbindungszeichenfolge nach dem Kopieren in eine neue Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird. Öffnen Sie zum Festlegen der Umgebungsvariablen ein Konsolenfenster, und befolgen Sie die Anleitung für Ihr Betriebssystem. Ersetzen Sie <yourconnectionstring> durch Ihre Verbindungszeichenfolge.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Sie müssen nach dem Hinzufügen der Umgebungsvariablen unter Windows eine neue Instanz des Befehlsfensters öffnen.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Das folgende Codebeispiel ruft die Verbindungszeichenfolge für das Speicherkonto aus der zuvor erstellten Umgebungsvariablen ab und verwendet die Verbindungszeichenfolge, um ein Clientobjekt für den Dienst zu erstellen.

Fügen Sie am Ende von main() den folgenden Code hinzu:

    // 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);

Wichtig

Der Kontozugriffsschlüssel sollte mit Vorsicht verwendet werden. Wenn Ihr Kontozugriffsschlüssel verloren geht oder versehentlich an einem unsicheren Ort gespeichert wird, kann Ihr Dienst anfällig werden. Jeder, der über den Zugriffsschlüssel verfügt, kann Anforderungen für das Speicherkonto autorisieren und hat somit Zugriff auf alle Daten. DefaultAzureCredential bietet erweiterte Sicherheitsfeatures und Vorteile und ist der empfohlene Ansatz zum Verwalten der Autorisierung für Azure-Dienste.

Erstellen eines Containers

Legen Sie einen Namen für den neuen Container fest. Erstellen Sie dann eine Instanz von BlobContainerClient, und erstellen Sie den Container.

Wichtig

Die Containernamen müssen klein geschrieben werden. Weitere Informationen zum Benennen von Containern und Blobs finden Sie unter Naming and Referencing Containers, Blobs, and Metadata (Benennen von Containern, Blobs und Metadaten und Verweisen auf diese).

Fügen Sie am Ende von main() den folgenden Code hinzu:

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();

Hochladen von Blobs in einen Container

Der folgende Codeausschnitt führt folgende Aktionen durch:

1. Deklariert eine Zeichenfolge, die „Hello Azure!“ enthält
2. Abrufen eines Verweises auf ein BlockBlobClient-Objekt durch Aufrufen von GetBlockBlobClient für den Container aus dem Abschnitt Erstellen eines Containers
3. Hochladen der Zeichenfolge in das Blob durch Aufrufen der Funktion UploadFrom. Mit dieser Funktion wird das Blob erstellt, falls es nicht bereits vorhanden ist, oder aktualisiert, falls es bereits vorhanden ist.

Fügen Sie am Ende von main() den folgenden Code hinzu:

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

Auflisten der Blobs im Container

Listen Sie die Blobs im Container auf, indem Sie die ListBlobs-Funktion aufrufen. Dem Container wurde nur ein Blob hinzugefügt, sodass bei diesem Vorgang nur dieses Blob zurückgegeben wird.

Fügen Sie am Ende von main() den folgenden Code hinzu:

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

Herunterladen von Blobs

Rufen Sie die Eigenschaften des aktualisierten Blobs ab. Deklarieren Sie anschließend ein neues std::vector<uint8_t>-Objekt, und ändern Sie seine Größe, indem Sie die Eigenschaften des hochgeladenen Blobs verwenden. Laden Sie das zuvor erstellte Blob in das neue std::vector<uint8_t>-Objekt herunter, indem Sie die Funktion DownloadTo in der BlobClient-Basisklasse aufrufen. Zeigen Sie abschließend die heruntergeladenen Blobdaten an.

Fügen Sie am Ende von main() den folgenden Code hinzu:

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;

Löschen eines Blobs

Mit dem folgenden Code wird das Blob durch Aufrufen der Funktion BlobClient.Delete aus dem Azure Blob Storage-Container gelöscht.

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

Löschen eines Containers

Im folgenden Code werden die von der App erstellten Ressourcen bereinigt, indem der gesamte Container mithilfe von BlobContainerClient.Delete gelöscht wird.

Fügen Sie am Ende von main() den folgenden Code hinzu:

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

Ausführen des Codes

Diese App erstellt einen Container und lädt eine Textdatei in Azure Blob Storage hoch. Im Beispiel werden dann die Blobs im Container aufgelistet, und die Datei wird heruntergeladen und der Dateiinhalt angezeigt. Schließlich löscht die App das Blob und den Container.

Die Ausgabe der App sieht etwa wie das folgende Beispiel aus:

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

Nächste Schritte

In dieser Schnellstartanleitung wurde beschrieben, wie Sie Blobs per C++ hochladen, herunterladen und auflisten. Außerdem haben Sie erfahren, wie Sie einen Azure Blob Storage-Container erstellen und löschen.

Ein C++-Blob Storage-Beispiel finden Sie hier:

Azure Blob Storage-Clientbibliothek für C++ – Beispiele