Démarrage rapide : Bibliothèque de client Stockage Blob Azure pour C++

  • Article

Commencez à utiliser la bibliothèque cliente Stockage Blob Azure pour C++. Le Stockage Blob Azure est la solution de stockage d’objets de Microsoft pour le cloud. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base.

| Documentation de référence sur les API | Code source de la bibliothèque | Exemples |

Prérequis

Configuration

Cette section vous guide tout au long de la préparation d’un projet à utiliser avec la bibliothèque cliente Stockage Blob Azure pour C++. Le moyen le plus simple d’acquérir le Kit de développement logiciel (SDK) Azure pour C++ consiste à utiliser le gestionnaire de package vcpkg.

Installer les packages

Utilisez la commande vcpkg install pour installer la bibliothèque Stockage Blob Azure pour C++ et les dépendances nécessaires :

vcpkg.exe install azure-storage-blobs-cpp

La bibliothèque Azure Identity est nécessaire pour les connexions sans mot de passe aux services Azure :

vcpkg.exe install azure-identity-cpp

Pour plus d’informations sur la configuration du projet et l’utilisation du Kit de développement logiciel (SDK) Azure pour C++, consultez le fichier lisez-moi du Kit de développement logiciel Azure pour C++.

Créer le projet

Dans Visual Studio, créez une nouvelle application console C++ pour Windows appelée BlobQuickstart.

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

Modèle objet

Stockage Blob Azure est optimisé pour stocker des quantités massives de données non structurées. Les données non structurées sont des données qui n’obéissent pas à un modèle ou une définition de données en particulier, comme des données texte ou binaires. Stockage Blob offre trois types de ressources :

  • Le compte de stockage
  • Un conteneur dans le compte de stockage.
  • Un blob dans le conteneur

Le diagramme suivant montre la relation entre ces ressources.

Diagram of Blob Storage architecture

Utilisez ces classes C++ pour interagir avec ces ressources :

  • BlobServiceClient: La classe BlobServiceClient vous permet de manipuler les ressources de stockage Azure et les conteneurs blob.
  • BlobContainerClient : La classe BlobContainerClient vous permet de manipuler des conteneurs de stockage Azure et leurs blobs.
  • BlobClient : La classe BlobClient vous permet de manipuler des blobs de stockage Azure. Il s’agit de la classe de base pour toutes les classes d’objets blob spécialisées.
  • BlockBlobClient: La classe BlockBlobClient vous permet de manipuler des objets blob de blocs de Stockage Azure.

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les tâches suivantes avec la bibliothèque de client Stockage Blob Azure pour C++ :

Ajouter des fichiers include

À partir du répertoire de projet :

  1. Ouvrez le fichier solution BlobQuickstart.sln dans Visual Studio
  2. Dans Visual Studio, ouvrez le fichier source BlobQuickstart.cpp
  3. Supprimez le code dans main qui a été généré automatiquement
  4. Ajoutez les instructions #include et using namespace
#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;

S’authentifier auprès d’Azure et autoriser l’accès aux données blob

Les demandes d’application vers le Stockage Blob Azure doivent être autorisées. L’utilisation de la classe DefaultAzureCredential fournie par la bibliothèque de client Azure Identity est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code, y compris le Stockage Blob.

Vous pouvez également autoriser les demandes vers le Stockage Blob Azure à l’aide de la clé d’accès au compte. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer la clé d’accès dans un emplacement non sécurisé. Toute personne disposant de la clé d’accès est en mesure d’autoriser les demandes sur le compte de stockage et a accès efficacement à toutes les données. DefaultAzureCredential offre des avantages améliorés en matière de gestion et de sécurité par rapport à la clé de compte pour autoriser l’authentification sans mot de passe. Les deux options sont illustrées dans l’exemple suivant.

La bibliothèque Azure Identity fournit une prise en charge de l’authentification par jeton Microsoft Entra dans le SDK Azure. Elle fournit un ensemble d’implémentations de TokenCredential, lesquelles permettent de construire des clients du SDK Azure en vue de la prise en charge de l’authentification par jeton Microsoft Entra. DefaultAzureCredential prend en charge plusieurs méthodes d’authentification et détermine quelle méthode doit être utilisée au moment de l’exécution.

Attribuer des rôles à votre compte d’utilisateur Microsoft Entra

Lors du développement local, assurez-vous que le compte d’utilisateur qui accède aux données blob dispose des autorisations appropriées. Vous aurez besoin du Contributeur aux données Blob de stockage pour lire et écrire des données blob. Pour vous attribuer ce rôle, vous aurez besoin du rôle Administrateur de l’accès utilisateur ou d’un autre rôle qui inclut l’action Microsoft.Authorization/roleAssignments/write. Vous pouvez attribuer des rôles RBAC Azure à un utilisateur à l’aide du Portail Azure, Azure CLI ou Azure PowerShell. Vous pouvez en savoir plus sur les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue .

Dans ce scénario, vous allez attribuer des autorisations à votre compte d’utilisateur, étendues au compte de stockage, pour suivre le Principe des privilèges minimum. Cette pratique offre aux utilisateurs uniquement les autorisations minimales nécessaires et crée des environnements de production plus sécurisés.

L’exemple suivant affecte le rôle Contributeur aux données Blob du stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données d’objet blob dans votre compte de stockage.

Important

Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes, mais dans de rares cas, cela peut prendre jusqu’à huit minutes. Si vous recevez des erreurs d’authentification lorsque vous exécutez votre code pour la première fois, patientez quelques instants et réessayez.

  1. Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.

  2. Dans la page vue d’ensemble du compte de stockage, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.

  3. Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.

  4. Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.

    A screenshot showing how to assign a role.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données Blob du stockage, sélectionnez le résultat correspondant, puis choisissez Suivant.

  6. Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.

  7. Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail utilisateur@domaine), puis choisissez Sélectionner en bas de la boîte de dialogue.

  8. Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Se connecter et connecter le code d’application à Azure à l’aide de DefaultAzureCredential

Vous pouvez autoriser l’accès aux données dans votre compte de stockage en procédant comme suit :

  1. Vérifiez que vous êtes authentifié avec le même compte Microsoft Entra auquel vous avez attribué le rôle sur votre compte de stockage. Vous pouvez vous authentifier via Azure CLI. Connectez-vous à Azure via Azure CLI à l’aide de la commande suivante :

    az login

  2. Pour utiliser DefaultAzureCredential, assurez-vous que le package azure-identity-cpp est installé et que le #include suivant est ajouté :

    #include <azure/identity/default_azure_credential.hpp>

  3. Ajoutez ce code à la fin de main(). Quand le code est exécuté sur votre station de travail locale, DefaultAzureCredential utilise les informations d’identification de développeur pour Azure CLI pour l’authentification dans 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. Veillez à mettre à jour le nom du compte de stockage dans l’URI de votre objet BlobServiceClient. Le nom du compte de stockage se trouve sur la page vue d’ensemble du Portail Azure.

    A screenshot showing how to find the storage account name.

    Remarque

    Lorsque vous utilisez le Kit de développement logiciel (SDK) C++ dans un environnement de production, il est recommandé d’activer uniquement les informations d’identification que votre application utilisera. Au lieu d’utiliser DefaultAzureCredential, vous devez autoriser l’utilisation d’un type d’informations d’identification spécifique, ou en utilisant ChainedTokenCredential avec les informations d’identification prises en charge.

Créez un conteneur.

Choisissez un nom pour le nouveau conteneur. Créez ensuite une instance de BlobContainerClient et créez le conteneur.

Important

Les noms de conteneurs doivent être en minuscules. Pour plus d’informations sur l’affectation de noms aux conteneurs et objets blob, consultez Affectation de noms et références aux conteneurs, objets blob et métadonnées.

Ajoutez ce code à la fin de 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();

Charger des objets blob sur un conteneur

L’extrait de code suivant :

  1. Déclare une chaîne contenant « Hello Azure! »
  2. Obtient une référence à un objet BlockBlobClient en appelant la méthode GetBlockBlobClient sur le conteneur provenant de la section Créer un conteneur.
  3. Charge la chaîne dans l’objet blob en appelant la fonction UploadFrom. Cette fonction crée l’objet blob s’il n’existe pas déjà ou le remplace s’il existe.

Ajoutez ce code à la fin de 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));

Lister les objets blob dans un conteneur

Répertoriez les objets Blob dans le conteneur en appelant la fonction ListBlobs. Un seul objet blob a été ajouté au conteneur : l’opération retourne donc seulement cet objet blob.

Ajoutez ce code à la fin de main() :

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

Télécharger des objets blob

Obtenez les propriétés de l’objet blob chargé. Ensuite, déclarez et redimensionnez un nouvel objet std::vector<uint8_t> en utilisant les propriétés de l’objet blob chargé. Téléchargez l’objet blob créé précédemment dans le nouvel objet std::vector<uint8_t> en appelant la fonction DownloadTo dans la classe de base BlobClient. Enfin, affichez les données de l’objet blob téléchargé.

Ajoutez ce code à la fin de 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;

Suppression d'un objet blob

Le code suivant supprime l’objet blob du conteneur Stockage Blob Azure en appelant la fonction BlobClient.Delete.

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

Supprimer un conteneur

Le code suivant nettoie les ressources créées par l’application en supprimant l’ensemble du conteneur avec BlobContainerClient.Delete.

Ajoutez ce code à la fin de main() :

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

Exécuter le code

Cette application crée un conteneur et charge un fichier texte dans Stockage Blob Azure. L’exemple liste ensuite le ou les objets blob du conteneur, télécharge le fichier et affiche le contenu du fichier. Enfin, l’application supprime l’objet blob et le conteneur.

La sortie de l’application ressemble à l’exemple suivant :

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

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez découvert comment charger, télécharger et lister des objets blob en utilisant C++. Vous avez également découvert comment créer et supprimer un conteneur Stockage Blob Azure.

Pour voir un exemple d’application Stockage Blob C++, passez à :

Bibliothèque de client Stockage Blob Azure pour des exemples C++