Partager via

Utiliser la Kit de développement logiciel (SDK) Azure pour les opérations de plan de données Go

Découvrez comment interagir avec les données stockées dans Azure services par programmation à l’aide de la Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes Go. Pour une introduction de niveau supérieur à la manière dont les bibliothèques de gestion et clientes s’intègrent, consultez la vue d'ensemble des bibliothèques de gestion Kit de développement logiciel (SDK) Azure pour Go. Cet article se concentre sur les modèles de plan de données Go que vous utilisez après qu’une ressource existe déjà, et pointe vers les opérations de plan de contrôle pour le provisionnement et le travail de configuration.

Qu’est-ce que le plan de données Azure ?

Le plan de données Azure est l’ensemble d’API que vous utilisez pour interagir avec les données à l’intérieur de Azure services, notamment le chargement d’objets blob, l’envoi de messages, l’interrogation des bases de données et la récupération des secrets. Pendant que le plan de contrôle provisionne et configure des ressources, le plan de données correspond à ce que votre code d’application appelle au moment de l’exécution. Un flux de travail Go courant consiste à utiliser le code du plan de commande une fois lors de l'installation ou de l'automatisation, puis à maintenir les clients du plan de données dans le parcours de l'application qui s'exécute chaque jour.

Le Kit de développement logiciel (SDK) Azure pour Go expose le plan de données via des packages spécifiques au service, tels que azblob, azservicebus, azeventhubs, azsecrets et azcosmos. Chaque package se connecte à une ressource déjà provisionnée et suit un modèle cohérent :

  1. Authentifiez-vous à l’aide du azidentity package.
  2. Créez un client typé à l’aide d’un point de terminaison de service ou d’une chaîne de connexion.
  3. Appelez des méthodes sur le client pour lire, écrire ou traiter des données.
  4. Gérez les résultats paginés et les erreurs.

Les scénarios courants pour les opérations de plan de données Go sont les suivants :

  • Chargement et téléchargement de fichiers à partir de Stockage Blob
  • Envoi et réception de messages avec Service Bus ou Event Hubs
  • Stockage et interrogation de documents dans Cosmos DB
  • Récupération de secrets, de clés et de certificats à partir de Key Vault
  • Supervision des performances des applications avec Application Insights

Authentification

Les opérations de plan de données prennent en charge les mêmes types d’informations d’identification à partir du package azidentity utilisé pour les opérations du plan de contrôle. Tous les types d’informations d’identification implémentent l’interface azcore.TokenCredential . Vous pouvez donc les échanger sans modifier le code client.

Les clients du plan de données nécessitent un point de terminaison de service (URL ou espace de noms) et des justificatifs, au lieu d'un ID d’abonnement.

// Create credential that auto-discovers authentication
cred, err := azidentity.NewDefaultAzureCredential(nil)

// Blob Storage - pass the storage account URL
blobClient, err := azblob.NewClient("https://mystorageaccount.blob.core.windows.net/", cred, nil)

// Key Vault secrets - pass the vault URL
secretClient, err := azsecrets.NewClient("https://mykeyvault.vault.azure.net/", cred, nil)

// Service Bus - pass the fully qualified namespace
sbClient, err := azservicebus.NewClient("mynamespace.servicebus.windows.net", cred, nil)

Certains services prennent également en charge les chaînes de connexion pour les environnements où l’authentification basée sur les jetons n’est pas disponible :

// Connection string authentication (when token auth is not available)
client, err := azservicebus.NewClientFromConnectionString(connectionString, nil)

Pour les charges de travail de production s’exécutant dans Azure, utilisez l’identité managée. Pour le développement local, DefaultAzureCredential détecte automatiquement les informations d’identification à partir des az loginvariables d’environnement ou d’autres sources.

Pour obtenir un guide complet sur les types d’informations d’identification et les bonnes pratiques, consultez Authentication avec la Kit de développement logiciel (SDK) Azure pour Go et la documentation du package azidentity.

Numérotation des pages

De nombreuses opérations de plan de données retournent des collections qui peuvent être volumineuses. Le Kit de développement logiciel (SDK) utilise un modèle de pagineur pour les opérations suivantes :

// Create a pager for listing large result sets
pager := client.NewListSecretPropertiesPager(nil)

// Iterate through pages until no more results
for pager.More() {
	page, err := pager.NextPage(ctx)
	if err != nil {
		return err
	}

	for _, item := range page.Value {
		fmt.Println(*item.ID)
	}
}

Les méthodes qui retournent des types *Pager suivent ce même modèle d'itération sur tous les paquets du plan de données.

Pour plus d’informations sur la pagination et d’autres modèles courants, consultez les modèles d’utilisation Common dans Kit de développement logiciel (SDK) Azure pour Go.

Gestion des erreurs

Les opérations de plan de données retournent des erreurs structurées que vous pouvez inspecter pour des codes d’erreur spécifiques :

import "github.com/Azure/azure-sdk-for-go/sdk/azcore"

// Check if the error is an Azure service error with structured details
var respErr *azcore.ResponseError
if errors.As(err, &respErr) {
	fmt.Printf("Error code: %s\n", respErr.ErrorCode)
	fmt.Printf("Status code: %d\n", respErr.StatusCode)
}

Les codes d’erreur courants du plan de données incluent BlobNotFound, MessageLockLost, SecretNotFoundet RequestEntityTooLarge. Consultez la documentation de chaque service pour obtenir la liste complète des codes d’erreur.

Télécharger un exemple de blob

Cet exemple montre un modèle prêt pour la production : authentifiez-vous à l’aide DefaultAzureCredential, créez un client blob, chargez des données avec un délai d’expiration et vérifiez. Ce modèle s’applique à tous les clients de plan de données. Échangez le point de terminaison de service et le type de client pour l’adapter pour Service Bus, Event Hubs, Cosmos DB ou Key Vault.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

func main() {
	accountURL := "https://<storage-account-name>.blob.core.windows.net/"
	containerName := "demo"
	blobName := "hello.txt"
	data := []byte("hello from Go")

	// Create credential that auto-discovers authentication
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to create credential: %v", err)
	}

	// Set a timeout to prevent hanging on network issues
	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	// Create a client for the storage account
	client, err := azblob.NewClient(accountURL, cred, nil)
	if err != nil {
		log.Fatalf("failed to create blob client: %v", err)
	}

	// Upload data directly from a byte slice
	_, err = client.UploadBuffer(ctx, containerName, blobName, data, nil)
	if err != nil {
		log.Fatalf("failed to upload blob: %v", err)
	}

	fmt.Printf("uploaded %s to container %s\n", blobName, containerName)
}

Stockage Blob

Le package azblob fournit un accès au plan de données à Stockage Blob Azure, un service de stockage d’objets massivement évolutif. Ce package est ce que votre application utilise au moment de l’exécution pour lire et écrire des données. Utilisez le package de plan de contrôle distinct armstorage pour approvisionner des comptes de stockage et des conteneurs.

Utilisez-le pour charger et télécharger des fichiers et des documents, répertorier et gérer des objets blob et des conteneurs, définir des métadonnées et des propriétés de contenu, implémenter des chargements parallèles pour les fichiers volumineux et générer des pipelines de traitement des données.

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

Pour commencer, consultez Quickstart : Stockage Blob Azure module client pour Go.

Pour obtenir la documentation du package, consultez la référence du package azblob.

Cosmos DB

Le package azcosmos fournit un accès au plan de données à Azure Cosmos DB, une base de données multimodèle distribuée à l’échelle mondiale. Utilisez-le pour générer des applications qui ont besoin de lectures et d’écritures à faible latence à n’importe quelle échelle.

Utilisez-le pour effectuer des opérations CRUD sur des documents, exécuter des requêtes SQL sur des conteneurs, gérer des stratégies de partitionnement pour un accès efficace aux données, gérer la pagination sur les jeux de résultats volumineux et exécuter des opérations de traitement par lots à plusieurs éléments.

go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos

Pour commencer, consultez Quickstart : Utilisez Azure Cosmos DB pour NoSQL avec Kit de développement logiciel (SDK) Azure pour Go.

Pour obtenir la documentation du package, consultez la référence du package azcosmos.

Hubs d’événements

Le package azeventhubs fournit un accès au plan de données à Azure Event Hubs - un service d’ingestion de données en temps réel pour la diffusion en continu d’événements à débit élevé.

Utilisez-le pour envoyer des événements par traitement par lots pour optimiser le débit, recevoir et traiter des événements à l’aide de groupes de consommateurs, gérer l'affectation des partitions et le pointage, router les événements à l’aide de clés de partition pour assurer l'ordre, et construire des pipelines d’ingestion de journaux et de télémétrie.

go get github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs

Pour commencer, consultez Démarrage rapide : Envoyer des événements vers ou recevoir des événements d’Event Hubs à l’aide de Go.

Pour obtenir la documentation du package, consultez la référence du package azeventhubs.

Key Vault

Les azsecrets, azkeys et azcertificates fournissent un accès au plan de données à Azure Key Vault. Ces packages que votre application utilise au moment de l’exécution pour récupérer des secrets et effectuer des opérations de chiffrement. Utilisez le package de plan de contrôle distinct armkeyvault pour approvisionner et configurer les instances Vault.

Utilisez-les pour récupérer et définir des secrets (mots de passe de base de données, clés API), créer et gérer des clés de chiffrement pour la signature et le chiffrement, gérer des certificats TLS/SSL avec renouvellement automatique, suivre les versions de secrets et implémenter des stratégies de rotation et mettre en cache des secrets pour réduire la latence et les appels d’API.

go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets
go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys
go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azcertificates

Pour commencer à utiliser Key Vault, consultez Quickstart : Azure Key Vault bibliothèque de client de certificat pour Go.

Pour obtenir la documentation du package, consultez les références de package azsecrets, azkeys et azcertificates.

Service Bus

Le package azservicebus fournit un accès au plan de données à Azure Service Bus - un répartiteur de messages entièrement géré pour une communication asynchrone fiable.

Utilisez-le pour envoyer et recevoir des messages sur des files d’attente pour la communication point à point, publier et s’abonner à des rubriques pour les modèles de fan-out, envoyer des lots de messages pour un débit efficace, planifier des messages pour la remise ultérieure et implémenter des consommateurs d’interrogation de longue durée avec achèvement et abandon des messages.

go get github.com/Azure/azure-sdk-for-go/sdk/messaging/azservicebus

Pour commencer à utiliser Azure Service Bus, consultez Démarrage rapide : Envoyer des messages à et recevoir des messages des files d'attente Azure Service Bus (Go).

Pour obtenir la documentation du package, consultez la référence du package azservicebus.

Application Insights

Le module ApplicationInsights-Go fournit une intégration des données de télémétrie avec Azure Application Insights - service APM (Application Performance Monitoring) de Azure.

Utilisez-le pour suivre les événements et les métriques personnalisés, surveiller les temps de réponse et les échecs de l’API, implémenter le suivi distribué entre les services, enregistrer des exceptions avec des propriétés contextuelles et contrôler le volume de télémétrie avec échantillonnage.

go get github.com/microsoft/ApplicationInsights-Go

Pour obtenir la documentation du service, consultez la vue d’ensemble d’Application Insights.

Étapes suivantes

  • Last updated on