Freigeben über


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

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.

Visual Studio dialog for configuring a new C++ Windows console app

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.

Diagram of Blob Storage architecture

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

Ü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.

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.

  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.

    A screenshot showing how to assign a role.

  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.

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.

    A screenshot showing how to find the storage account name.

    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.

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: