Uso del SDK de Azure para Go para las operaciones del plano de datos

Obtenga información sobre cómo interactuar con los datos almacenados en Azure servicios mediante programación mediante el uso de la SDK de Azure para las bibliotecas cliente de Go. Para obtener una introducción de nivel superior sobre cómo encajan juntas las bibliotecas de administración y las bibliotecas cliente, consulte Información general de la SDK de Azure para bibliotecas de administración de Go. Este artículo se centra en los patrones de plano de datos de Go que se usan después de que ya existe un recurso y apunta a las operaciones del plano de control para el trabajo de aprovisionamiento y configuración.

¿Cuál es el plano de datos de Azure?

El Azure plano de datos es el conjunto de API que se usan para interactuar con los datos dentro de los servicios de Azure, incluida la carga de blobs, el envío de mensajes, la consulta de bases de datos y la recuperación de secretos. Aunque el plano de control aprovisiona y configura los recursos, el plano de datos es lo que llama el código de la aplicación en tiempo de ejecución. Un flujo de trabajo común en Go es utilizar el código del plano de control una vez durante la configuración o automatización, y luego mantener los clientes del plano de datos en la ruta de la aplicación que se ejecuta diariamente.

El SDK de Azure para Go expone el plano de datos a través de paquetes específicos del servicio, como azblobazservicebus, azeventhubs, azsecrets y azcosmos. Cada paquete se conecta a un recurso ya aprovisionado y sigue un patrón coherente:

1. Autentíquese mediante el azidentity paquete.
2. Cree un cliente tipado utilizando un punto de conexión de servicio o una cadena de conexión.
3. Llame a métodos en el cliente para leer, escribir o procesar datos.
4. Controle los resultados paginados y los errores.

Entre los escenarios comunes para las operaciones del plano de datos de Go se incluyen:

• Carga y descarga de archivos desde Blob Storage
• Envío y recepción de mensajes con Service Bus o Event Hubs
• Almacenamiento y consulta de documentos en Cosmos DB
• Recuperación de secretos, claves y certificados de Key Vault
• Supervisión del rendimiento de la aplicación con Application Insights

Autenticación

Las operaciones del plano de datos admiten los mismos tipos de credenciales del paquete azidentity usado para las operaciones del plano de control. Todos los tipos de credenciales implementan la azcore.TokenCredential interfaz, por lo que puede intercambiarlos sin cambiar el código de cliente.

Los clientes del plano de datos utilizan un extremo de servicio (dirección URL o espacio de nombres) y una credencial, en lugar de usar un ID de suscripción.

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

Algunos servicios también admiten cadenas de conexión para entornos en los que la autenticación basada en tokens no está disponible:

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

En el caso de las cargas de trabajo de producción que se ejecutan en Azure, use la identidad administrada. Para el desarrollo local, DefaultAzureCredential detecta automáticamente las credenciales de az login, variables de entorno u otros orígenes.

Para obtener una guía completa sobre los tipos de credenciales y los procedimientos recomendados, consulte Authentication con la SDK de Azure para Go y la documentación del paquete azidentity.

Paginación

Muchas operaciones del plano de datos devuelven colecciones que pueden ser grandes. El SDK usa un patrón de paginación para estas operaciones:

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

Los métodos que devuelven *Pager tipos siguen este mismo patrón de iteración en todos los paquetes del plano de datos.

Para obtener más información sobre la paginación y otros patrones comunes, consulte los patrones de uso de Common en SDK de Azure para Go.

Gestión de errores

Las operaciones del plano de datos devuelven errores estructurados que puede inspeccionar para ver códigos de error específicos:

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

Los códigos de error comunes del plano de datos incluyen BlobNotFound, MessageLockLost, SecretNotFoundy RequestEntityTooLarge. Compruebe la documentación de cada servicio para obtener la lista completa de códigos de error.

Carga de un ejemplo de blob

En este ejemplo se muestra un patrón listo para producción: autenticarse mediante DefaultAzureCredential, crear un cliente de blobs, cargar datos con un tiempo de espera y comprobarlos. Este patrón se aplica a todos los clientes del plano de datos. Cambie el punto de conexión de servicio y el tipo de cliente para adaptarlo a Service Bus, Event Hubs, 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)
}

Almacenamiento de Blobs

El paquete azblob proporciona acceso al plano de datos a Azure Blob Storage, un servicio de almacenamiento de objetos escalable de forma masiva. Este paquete es lo que usa la aplicación en tiempo de ejecución para leer y escribir datos. Use el paquete de plano de control independiente armstorage para aprovisionar cuentas de almacenamiento y contenedores.

Úselo para cargar y descargar archivos y documentos, enumerar y administrar blobs y contenedores, establecer metadatos y propiedades de contenido, implementar cargas paralelas para archivos grandes y crear canalizaciones de procesamiento de datos.

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

Para empezar, consulte Quickstart: módulo cliente de Azure Blob Storage para Go.

Para obtener la documentación del paquete, consulte la referencia del paquete azblob.

Cosmos DB

El paquete azcosmos proporciona acceso al plano de datos a Azure Cosmos DB, una base de datos multimodelo distribuida globalmente. Úselo para compilar aplicaciones que necesitan lecturas y escrituras de baja latencia a cualquier escala.

Úselo para realizar operaciones CRUD en documentos, ejecutar consultas SQL en contenedores, administrar estrategias de creación de particiones para un acceso eficaz a los datos, controlar la paginación sobre grandes conjuntos de resultados y ejecutar operaciones por lotes de varios elementos.

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

Para empezar, consulte Quickstart: Use Azure Cosmos DB for NoSQL with SDK de Azure for Go.

Para obtener la documentación del paquete, consulte la referencia del paquete azcosmos.

Centros de eventos

El paquete azeventhubs proporciona acceso al plano de datos a Azure Event Hubs: un servicio de ingesta de datos en tiempo real para el streaming de eventos de alto rendimiento.

Úselo para enviar eventos con procesamiento por lotes para lograr un rendimiento eficaz, recibir y procesar eventos mediante grupos de consumidores, administrar la asignación de particiones y puntos de control, enrutar eventos mediante claves de partición para ordenar garantías y generar canalizaciones de telemetría y ingesta de registros.

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

Para empezar, consulte Inicio rápido: Envío o recepción de eventos desde Event Hubs mediante Go.

Para obtener la documentación del paquete, consulte la referencia del paquete azeventhubs.

Key Vault

Los paquetes azsecrets, azkeys y azcertificates proporcionan acceso al plano de datos a Azure Key Vault. Estos paquetes que usa la aplicación en tiempo de ejecución para recuperar secretos y realizar operaciones criptográficas. Utilice el paquete de plano de control independiente armkeyvault para aprovisionar y configurar instancias de Vault.

Úselos para recuperar y establecer secretos (contraseñas de base de datos, claves de API), crear y administrar claves criptográficas para firmar y cifrar, administrar certificados TLS/SSL con renovación automática, realizar un seguimiento de las versiones secretas e implementar estrategias de rotación y almacenar en caché secretos para reducir la latencia y las llamadas 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

Para empezar a trabajar con Key Vault, consulte Quickstart: Azure Key Vault biblioteca cliente de certificados para Go.

Para obtener la documentación del paquete, consulte las referencias de paquete azsecrets, azkeys y azcertificates.

Bus de Servicios

El paquete azservicebus proporciona acceso al plano de datos a Azure Service Bus, un agente de mensajes totalmente administrado para una comunicación asincrónica confiable.

Úselo para enviar y recibir mensajes en colas para la comunicación de punto a punto, publicar y suscribirse a temas para patrones de distribución ramificada, enviar lotes de mensajes para un rendimiento eficaz, programar mensajes para la entrega futura e implementar consumidores de sondeo largo con finalización y abandono de mensajes.

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

Para empezar a trabajar con Azure Service Bus, consulte Quickstart: Envío de mensajes a colas de Azure Service Bus (Go).

Para obtener la documentación del paquete, consulte la referencia del paquete azservicebus.

Application Insights

El módulo ApplicationInsights-Go proporciona integración de telemetría con Aplicación de Azure Insights: el servicio de supervisión del rendimiento de las aplicaciones (APM) de Azure.

Úselo para realizar un seguimiento de eventos y métricas personalizados, supervisar los tiempos de respuesta y los errores de la API, implementar el seguimiento distribuido entre servicios, registrar excepciones con propiedades contextuales y controlar el volumen de telemetría con muestreo.

go get github.com/microsoft/ApplicationInsights-Go

Para obtener la documentación del servicio, consulte introducción a Application Insights.

Pasos siguientes

• Información general de la SDK de Azure para las bibliotecas de administración de Go
• Utiliza el SDK de Azure para Go para operaciones en el plano de control
• SDK de Azure para Go Authentication
• SDK de Azure para ejemplos de Go en GitHub