Usare l'Azure SDK per Go per le operazioni del piano dati

Informazioni su come interagire con i dati archiviati nei servizi Azure a livello di codice usando le librerie client di Azure SDK for Go. Per un'introduzione di livello superiore al modo in cui le librerie di gestione e le librerie client si integrano, vedere Panoramica delle librerie di gestione di Azure SDK Go. Questo articolo è incentrato sui modelli di data-plane di Go utilizzati dopo l'esistenza di una risorsa e rimanda alle operazioni del control plane per il lavoro di provisioning e configurazione.

Che cos'è il piano dati Azure?

Il piano dati Azure è il set di API usate per interagire con i dati all'interno di Azure servizi, tra cui il caricamento di BLOB, l'invio di messaggi, l'esecuzione di query sui database e il recupero dei segreti. Mentre il piano di controllo effettua il provisioning e configura le risorse, il piano dati è ciò che il codice dell'applicazione chiama in fase di esecuzione. Un comune flusso di lavoro con Go consiste nell'usare il codice del control plane una sola volta durante la configurazione o l'automazione, e quindi mantenere i client del data plane nel percorso dell'applicazione che si esegue quotidianamente.

Il Azure SDK per Go espone il piano dati tramite pacchetti specifici del servizio, ad esempio azblobazservicebus, azeventhubs, azsecrets e azcosmos. Ogni pacchetto si connette a una risorsa di cui è già stato effettuato il provisioning e segue un modello coerente:

1. Eseguire l'autenticazione usando il azidentity pacchetto.
2. Creare un client tipizzato usando un endpoint di servizio o un stringa di connessione.
3. Chiamare i metodi sul client per leggere, scrivere o elaborare i dati.
4. Gestire i risultati impaginati e gli errori.

Gli scenari comuni per le operazioni del piano dati Go includono:

• Caricamento e download di file da gestione rete virtuale di Azure
• Invio e ricezione di messaggi con bus di servizio o Hub eventi
• Archiviazione ed esecuzione di query su documenti in Cosmos DB
• Recupero di segreti, chiavi e certificati da Key Vault
• Monitoraggio delle prestazioni dell'applicazione con Application Insights

Autenticazione

Le operazioni del piano dati supportano gli stessi tipi di credenziali del pacchetto azidentity usato per le operazioni del piano di controllo. Tutti i tipi di credenziali implementano l'interfaccia, in modo da poterli scambiare senza modificare il azcore.TokenCredential codice client.

I client del piano dati accettano un endpoint di servizio (URL o spazio dei nomi) e una credenziale, anziché un ID di sottoscrizione.

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

Alcuni servizi supportano anche stringhe di connessione per gli ambienti in cui l'autenticazione basata su token non è disponibile:

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

Per i carichi di lavoro di produzione in esecuzione in Azure, usare l'identità gestita. Per lo sviluppo locale, DefaultAzureCredential individua automaticamente le credenziali da az login, variabili di ambiente o altre origini.

Per una guida completa sui tipi di credenziali e sulle procedure consigliate, vedere Authentication with the Azure SDK for Go and the azidentity package documentation.

Impaginazione

Molte operazioni del piano dati restituiscono raccolte di grandi dimensioni. L'SDK usa un pattern paginatore per queste operazioni:

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

I metodi che restituiscono *Pager tipi seguono questo stesso modello di iterazione in tutti i pacchetti del piano dati.

Per ulteriori dettagli sull'impaginazione e altri modelli comuni, consultare i modelli di utilizzo comuni nell'Azure SDK per Go.

Gestione degli errori

Le operazioni del piano dati restituiscono errori strutturati che è possibile esaminare per individuare codici di errore specifici:

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

I codici di errore comuni del piano dati includono BlobNotFound, MessageLockLost, SecretNotFounde RequestEntityTooLarge. Controllare la documentazione per ogni servizio per l'elenco completo dei codici di errore.

Esempio di caricamento di un BLOB

Questo esempio mostra un modello pronto per la produzione: eseguire l'autenticazione usando DefaultAzureCredential, creare un client BLOB, caricare dati con un timeout e verificare. Questo modello si applica a tutti i client del piano dati. Scambiare l'endpoint di servizio e il tipo di client per adattarlo per bus di servizio, Hub eventi, Cosmos DB o 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)
}

Archiviazione Blob

Il pacchetto azblob fornisce l'accesso al piano dati a Archiviazione BLOB di Azure, un servizio di archiviazione oggetti altamente scalabile. Questo pacchetto è ciò che l'applicazione usa in fase di esecuzione per leggere e scrivere dati. Usa il pacchetto separato del piano di controllo armstorage per provisionare account di archiviazione e contenitori.

Usarlo per caricare e scaricare file e documenti, elencare e gestire BLOB e contenitori, impostare metadati e proprietà del contenuto, implementare caricamenti paralleli per file di grandi dimensioni e creare pipeline di elaborazione dati.

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

Per iniziare, vedere Quickstart: modulo client Archiviazione BLOB di Azure per Go.

Per la documentazione del pacchetto, vedere le informazioni di riferimento sul pacchetto azblob.

Cosmos DB

Il pacchetto azcosmos fornisce l'accesso al piano dati per Azure Cosmos DB, un database multimodello distribuito a livello globale. Usarlo per creare applicazioni che necessitano di letture e scritture a bassa latenza su qualsiasi scala.

Usarlo per eseguire operazioni CRUD sui documenti, eseguire query SQL su contenitori, gestire strategie di partizionamento per un accesso efficiente ai dati, gestire la paginazione su set di risultati di grandi dimensioni ed eseguire operazioni batch su più elementi.

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

Per iniziare, vedere Quickstart: Usare Azure Cosmos DB per NoSQL con Azure SDK per Go.

Per la documentazione del pacchetto, vedere le informazioni di riferimento sul pacchetto azcosmos.

Centri eventi

Il pacchetto azeventhubs fornisce l'accesso al piano dei dati di Hub eventi di Azure, un servizio di inserimento dati in tempo reale per lo streaming di eventi ad alto throughput.

Usarlo per inviare eventi con invio in batch per ottimizzare l'efficienza del throughput, ricevere ed elaborare eventi usando i gruppi di consumatori, gestire l'assegnazione delle partizioni e la gestione dei checkpoint, indirizzare gli eventi usando chiavi di partizione per garantire l'ordinamento e sviluppare pipeline di acquisizione e telemetria dei log.

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

Per iniziare, vedere Guida introduttiva: Inviare o ricevere eventi da Hub eventi con Go.

Per la documentazione del pacchetto, vedere le informazioni di riferimento sul pacchetto azeventhubs.

Key Vault

I pacchetti azsecrets, azkeys e azcertificates forniscono l'accesso al piano dati a Azure Key Vault. Questi pacchetti usati dall'applicazione in fase di esecuzione per recuperare i segreti ed eseguire operazioni di crittografia. Usare il pacchetto del piano di controllo separato armkeyvault per effettuare il provisioning e configurare le istanze di vault.

Usarli per recuperare e impostare segreti (password del database, chiavi API), creare e gestire chiavi crittografiche per la firma e la crittografia, gestire i certificati TLS/SSL con rinnovo automatico, tenere traccia delle versioni dei segreti e implementare strategie di rotazione e memorizzare nella cache i segreti per ridurre la latenza e le chiamate 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

Per iniziare a usare Key Vault, vedere Guida rapida: Libreria client dei certificati di Azure Key Vault per Go.

Per la documentazione del pacchetto, vedere i riferimenti ai pacchetti azsecrets, azkeys e azcertificates.

Bus di Servizio

Il pacchetto azservicebus fornisce l'accesso al piano dati a bus di servizio di Azure, ovvero un broker di messaggi completamente gestito per una comunicazione asincrona affidabile.

Usarlo per inviare e ricevere messaggi nelle code per la comunicazione da punto a punto, pubblicare e sottoscrivere topic per modelli di fan-out, inviare batch di messaggi per una velocità effettiva efficiente, pianificare i messaggi per il recapito futuro e implementare consumer di long-polling con completamento e abbandono dei messaggi.

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

Per iniziare a usare bus di servizio di Azure, vedere Guida rapida: Inviare e ricevere messaggi dalle code di bus di servizio di Azure (Go).

Per la documentazione del pacchetto, vedere le informazioni di riferimento sul pacchetto azservicebus.

Approfondimenti sulle Applicazioni

Il modulo ApplicationInsights-Go fornisce l'integrazione dei dati di telemetria con applicazione Azure Insights - servizio di monitoraggio delle prestazioni delle applicazioni (APM) di Azure.

Usarlo per tenere traccia di eventi e metriche personalizzati, monitorare i tempi di risposta e gli errori dell'API, implementare la traccia distribuita tra servizi, registrare le eccezioni con proprietà contestuali e controllare il volume dei dati di telemetria con il campionamento.

go get github.com/microsoft/ApplicationInsights-Go

Per la documentazione del servizio, vedere la panoramica di Application Insights.

Passaggi successivi

• Panoramica del Azure SDK per le librerie di gestione Go
• Usare il Azure SDK per le operazioni del piano di controllo
• Azure SDK per l'autenticazione Go
• Azure SDK per i campioni di Go su GitHub