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

Article
08/29/2023

Commencez à utiliser la bibliothèque de client Stockage Blob Azure pour Go pour gérer les objets blob et les conteneurs. 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 | Package (pkg.go.dev)

Prérequis

Abonnement Azure : créez-en un gratuitement
Compte de stockage Azure : créez un compte de stockage
Go 1.18+

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

Téléchargement de l'exemple d'application

L’exemple d’application utilisé dans ce démarrage rapide est une application Go de base.

Utilisez git pour télécharger une copie de l’application dans votre environnement de développement.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart

Cette commande clone le dépôt dans votre dossier git local. Pour ouvrir l’exemple Go pour le stockage blob, recherchez le fichier nommé storage-quickstart.go.

Installer les packages

Pour utiliser des ressources d’objet blob et de conteneur dans un compte de stockage, installez le package azblob à l’aide de la commande suivante :

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Pour vous authentifier auprès de Microsoft Entra ID (recommandé), installez le module azidentity en utilisant la commande suivante :

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

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 DefaultAzureCredential et la bibliothèque de client d’identité Azure est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code, y compris 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.

DefaultAzureCredential est une implémentation de chaîne d’informations d'identification fournie par la bibliothèque de client Azure Identity pour Go. 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. Cette approche permet à votre application d’utiliser différentes méthodes d’authentification dans différents environnements (local ou production) sans implémenter de code spécifique à l’environnement.

Pour en savoir plus sur l’ordre et les emplacements dans lesquels DefaultAzureCredential les informations d’identification sont disponibles dans la vue d’ensemble de la bibliothèque d’identités Azure.

Par exemple, votre application peut s’authentifier à l’aide de vos informations d’identification de connexion Azure CLI lors du développement local. Une fois qu’elle est déployée sur Azure, votre application peut ensuite utiliser une identité managée. Cette transition entre les environnements ne nécessite aucune modification du code.

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.

Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.
Dans la page vue d’ensemble du compte de stockage, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.
Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.
Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.
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.
Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.
Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail user@domain), puis choisissez Sélectionner en bas de la boîte de dialogue.
Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Pour attribuer un rôle au niveau de la ressource à l’aide d’Azure CLI, vous devez d’abord récupérer l’ID de ressource à l’aide de la commande az storage account show. Vous pouvez filtrer les propriétés de sortie à l’aide du paramètre --query.

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

Copiez la sortie Id de la commande précédente. Vous pouvez ensuite attribuer des rôles à l’aide de la commande az role de l’interface de ligne de commande Azure.

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

Pour attribuer un rôle au niveau de la ressource à l’aide d’Azure PowerShell, vous devez d’abord récupérer l’ID de ressource à l’aide de la commande Get-AzResource.

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

Copiez la valeur Id de la sortie de commande précédente. Vous pouvez ensuite attribuer des rôles à l’aide de la commande New-AzRoleAssignment dans PowerShell.

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

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

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. L’exemple suivant montre comment s’authentifier via Azure CLI :
```
az login
```
Pour utiliser DefaultAzureCredential dans une application Go, installez le module azidentity à l’aide de la commande suivante :
```
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
```

L’authentification Azure CLI n’est pas recommandée pour les applications s’exécutant dans Azure. Lorsqu’il est déployé sur Azure, vous pouvez utiliser ce même code pour autoriser les demandes adressées à Stockage Azure à partir d’une application s’exécutant dans Azure. Toutefois, vous devez activer l’identité managée sur votre application dans Azure et configurer votre compte de stockage pour permettre à cette identité managée de se connecter. Pour obtenir des instructions détaillées sur la configuration de cette connexion entre les services Azure, consultez le didacticiel d’authentification à partir d’applications hébergées sur Azure .

Pour en savoir plus sur les différentes méthodes d’authentification, consultez l’authentification Azure avec Azure SDK pour Go.

Exécution de l'exemple

L’exemple de code effectue les actions suivantes :

Crée un objet client autorisé pour l’accès aux données via DefaultAzureCredential
Crée un conteneur dans un compte de stockage.
Charge un objet blob dans le conteneur.
Liste les objets blob du conteneur.
Télécharge les données d’objet blob dans une mémoire tampon.
Supprime les ressources d’objet blob et de conteneur créées par l’application.

Avant d’exécuter cet exemple de code, ouvrez le fichier storage-quickstart.go. Remplacez <storage-account-name> par le nom de votre compte de stockage Azure.

Ensuite, exécutez l’application à l’aide de la commande suivante :

go run storage-quickstart.go

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

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

Lorsque vous appuyez sur la touche Entrée à l’invite, l’exemple de programme supprime les ressources d’objet blob et de conteneur créées par l’application.

Conseil

Vous pouvez également utiliser un outil comme l’Explorateur Stockage Azure pour afficher les fichiers dans Stockage Blob. L’Explorateur Stockage Azure est un outil multiplateforme gratuit qui vous permet d’accéder aux informations de votre compte de stockage.

Comprendre l’exemple de code

Parcourons maintenant l’exemple de code pour comprendre son fonctionnement.

Autoriser l’accès et créer un objet client

L’utilisation des ressources Azure à l’aide du Kit de développement logiciel (SDK) commence par la création d’un objet client. Pour créer l’objet client, l’exemple de code appelle azblob. NewClient avec les valeurs suivantes :

serviceURL : URL du compte de stockage
cred - informations d’identification Microsoft Entra obtenues via le module azidentity
options : options du client ; pass nil pour accepter les valeurs par défaut

L’exemple de code suivant crée un objet client pour interagir avec les ressources de conteneur et d’objet blob dans un compte de stockage :

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

client, err := azblob.NewClient(url, credential, nil)
handleError(err)

Créez un conteneur.

L’exemple de code crée une ressource conteneur dans le compte de stockage. Si un conteneur portant le même nom existe déjà, un ResourceExistsError est déclenché.

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.

L’exemple de code suivant crée un conteneur appelé quickstart-sample-container dans le compte de stockage :

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

Charger des objets blob dans le conteneur

L’exemple de code crée un tableau d’octets avec des données et charge les données en tant que mémoire tampon vers une nouvelle ressource d’objet blob dans le conteneur spécifié.

L’exemple de code suivant charge les données blob dans le conteneur spécifié à l’aide de la méthode UploadBuffer :

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

Créer la liste des objets blob d’un conteneur

L’exemple de code répertorie les objets blob dans le conteneur spécifié. Cet exemple utilise NewListBlobsFlatPager, qui retourne un pager pour les objets blob à partir du marqueur spécifié. Ici, nous utilisons un marqueur vide pour démarrer l’énumération à partir du début et poursuivre la pagination jusqu’à ce qu’il n’y ait plus de résultats. Cette méthode retourne les noms d’objets blob dans l’ordre lexicographique.

L’exemple suivant liste les objets blob dans le conteneur spécifié :

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

for pager.More() {
	resp, err := pager.NextPage(context.TODO())
	handleError(err)

	for _, blob := range resp.Segment.BlobItems {
		fmt.Println(*blob.Name)
	}
}

Télécharger l’objet blob

L’exemple de code télécharge un objet blob à l’aide de la méthode DownloadStream et crée un lecteur de nouvelle tentative pour la lecture des données. Si une connexion échoue lors de la lecture, d’autres requêtes sont envoyées pour rétablir une connexion et poursuivre la lecture. Vous pouvez spécifier les options de lecteur de nouvelle tentative à l’aide du struct RetryReaderOptions.

L’exemple de code suivant télécharge un objet blob et écrit le contenu dans la console :

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

Nettoyer les ressources

Si vous n’avez plus besoin des objets blob chargés dans ce guide de démarrage rapide, vous pouvez supprimer l’objet blob individuel à l’aide de la méthode DeleteBlob, ou le conteneur entier et son contenu à l’aide de la méthode DeleteContainer.

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

É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 Go.

Pour afficher des exemples d’applications de stockage blob, passez à :

Exemples de bibliothèque Stockage Blob Azure pour Go

Pour plus d’informations, consultez la bibliothèque cliente Stockage Blob Azure pour Go.
Pour consulter des tutoriels, des exemples, des guides de démarrage rapide et autre documentation, consultez Azure pour les développeurs Go.