Partilhar via

Utilize o SDK do Azure para Go para operações no plano de dados.

Aprenda a interagir programáticamente com dados armazenados nos serviços do Azure utilizando as bibliotecas do cliente SDK do Azure for Go. Para uma introdução a um nível mais avançado sobre como as bibliotecas de gestão e as bibliotecas clientes se encaixam, veja Visão Geral do SDK do Azure para bibliotecas de gestão do Go. Este artigo foca-se nos padrões de plano de dados Go que utiliza depois de um recurso já existir, e remete para as operações do plano de controlo para o trabalho de provisionamento e configuração.

O que é o plano de dados do Azure?

O plano de dados do Azure é o conjunto de APIs que utilizas para interagir com dados dentro dos serviços do Azure, incluindo carregar blobs, enviar mensagens, consultar bases de dados e recuperar segredos. Enquanto o plano de controlo fornece e configura recursos, o plano de dados é o que o código da aplicação chama em tempo de execução. Um fluxo de trabalho comum no Go é usar o código da camada de controlo uma vez na configuração ou automação, e depois manter os clientes da camada de dados no percurso da aplicação que corre diariamente.

O SDK do Azure para o Go expõe o plano de dados através de pacotes específicos de serviço como azblob, azservicebus, azeventhubs, azsecrets e azcosmos. Cada pacote liga-se a um recurso já provisionado e segue um padrão consistente:

  1. Autentique usando o azidentity pacote.
  2. Crie um cliente tipado usando um endpoint de serviço ou uma string de conexão.
  3. Chamar métodos no cliente para ler, escrever ou processar dados.
  4. Gerir resultados paginados e erros.

Cenários comuns para operações no plano de dados Go incluem:

  • Carregar e descarregar ficheiros do Armazenamento de Blobs
  • Envio e receção de mensagens com Service Bus ou Event Hubs
  • Armazenar e consultar documentos no Cosmos DB
  • Recuperar segredos, chaves e certificados do Key Vault
  • Monitorização do desempenho da aplicação com Application Insights

Authentication

As operações do plano de dados suportam os mesmos tipos de credenciais do pacote azidentity usado para operações no plano de controlo. Todos os tipos de credenciais implementam a azcore.TokenCredential interface, por isso podes trocá-las sem alterar o código do cliente.

Os clientes do plano de dados recebem um endpoint de serviço (URL ou namespace) e uma credencial, em vez de um ID de subscrição:

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

Alguns serviços também suportam strings de ligação para ambientes onde a autenticação baseada em token não está disponível:

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

Para cargas de trabalho de produção a correr no Azure, use identidade gerida. Para desenvolvimento local, DefaultAzureCredential descobre automaticamente credenciais a partir de az loginvariáveis de ambiente ou outras fontes.

Para um guia completo sobre tipos de credenciais e melhores práticas, consulte Autenticação com a SDK do Azure para Go e a documentação do pacote azidentity.

Paginação

Muitas operações de plano de dados retornam coleções que podem ser grandes. O SDK utiliza um padrão de pager para estas operações:

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

Os métodos que retornam *Pager tipos seguem este mesmo padrão de iteração em todos os pacotes de planos de dados.

Para mais detalhes sobre paginação e outros padrões comuns, consulte o Padrões de uso comum em SDK do Azure for Go.

Tratamento de erros

As operações no plano de dados devolvem erros estruturados que pode inspecionar para códigos de erro 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)
}

Códigos de erro comuns nos planos de dados incluem BlobNotFound, MessageLockLost, SecretNotFound, e RequestEntityTooLarge. Consulte a documentação de cada serviço para a lista completa de códigos de erro.

Carregar um exemplo de blob

Este exemplo mostra um padrão pronto para produção: autenticar usando DefaultAzureCredential, criar um cliente blob, carregar dados com um timeout e verificar. Este padrão aplica-se a todos os clientes do plano de dados. Troca o endpoint de serviço e o tipo de cliente para o adaptar ao 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)
}

Armazenamento de Blobs

O pacote azblob fornece acesso ao plano de dados ao Armazenamento de Blobs do Azure, um serviço de armazenamento de objetos massivamente escalável. Este pacote é o que a sua aplicação usa em tempo de execução para ler e escrever dados. Use o pacote de plano de controlo separado armstorage para provisionar contas de armazenamento e contentores.

Use-o para carregar e descarregar ficheiros e documentos, listar e gerir blobs e contentores, definir metadados e propriedades de conteúdo, implementar uploads paralelos para ficheiros grandes e construir pipelines de processamento de dados.

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

Para começar, veja Quickstart: Armazenamento de Blobs do Azure módulo cliente para Go.

Para a documentação do pacote, consulte a referência do pacote azblob.

Cosmos DB

O pacote azcosmos fornece acesso ao plano de dados do Azure Cosmos DB, uma base de dados globalmente distribuída e multimodelo. Use-o para construir aplicações que necessitem de leituras e escritas de baixa latência em qualquer escala.

Utilize-o para realizar operações CRUD em documentos, executar consultas SQL em contentores, gerir estratégias de particionamento para acesso eficiente aos dados, gerir a paginação em grandes conjuntos de resultados e executar operações em lote com múltiplos itens.

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

Para começar, consulte Início rápido: Use o Azure Cosmos DB para NoSQL com o SDK do Azure para Go.

Para a documentação do pacote, consulte a referência do pacote azcosmos.

Hubs de Eventos

O pacote azeventhubs fornece acesso ao plano de dados do Hubs de Eventos do Azure – um serviço de ingestão de dados em tempo real para streaming de eventos de alto rendimento.

Utilize-o para enviar eventos com processamento em lotes para um throughput eficiente, receber e processar eventos usando grupos de consumidores, gerir a atribuição de partições e a marcação de pontos de verificação, encaminhar eventos usando chaves de partição para garantias de ordenação, e construir fluxos de ingestão de logs e telemetria.

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

Para começar, consulte Início Rápido: Enviar eventos para ou receber eventos dos Centros de Eventos usando o Go.

Para a documentação do pacote, consulte a referência do pacote azeventhubs.

Key Vault (cofre de chaves)

Os pacotes azsecrets, azkeys e azcertificates fornecem acesso ao plano de dados a Azure Key Vault. Estes pacotes que a sua aplicação utiliza em tempo de execução para recuperar segredos e realizar operações criptográficas. Use o pacote de plano de controlo separado armkeyvault para provisionar e configurar instâncias do vault.

Utilize-os para recuperar e definir segredos (palavras-passe de base de dados, chaves API), criar e gerir chaves criptográficas para assinatura e encriptação, gerir certificados TLS/SSL com renovação automática, rastrear versões secretas e implementar estratégias de rotação, e armazenar segredos em cache para reduzir latência e chamadas 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 começar com Key Vault, consulte Quickstart: Azure Key Vault biblioteca de clientes de certificação para Go.

Para a documentação do pacote, consulte as referências de pacote azsecrets, azkeys e azcertificates.

Service Bus

O pacote azservicebus fornece acesso ao plano de dados ao Azure Service Bus – um corretor de mensagens totalmente gerido para comunicação assíncrona fiável.

Utilize-o para enviar e receber mensagens em filas para comunicação ponto a ponto, publicar e subscrever tópicos para padrões de dispersão, enviar lotes de mensagens para um throughput eficiente, agendar mensagens para entregas futuras e implementar consumidores de sondagens longas com conclusão e abandono de mensagens.

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

Para começar com o Azure Service Bus, veja Início rápido: Enviar mensagens para e receber mensagens de filas do Azure Service Bus (Go).

Para a documentação do pacote, consulte a referência do pacote azservicebus.

Application Insights

O módulo ApplicationInsights-Go fornece integração de telemetria com o Aplicação Azure Insights - o serviço de monitorização de desempenho da aplicação (APM) da Azure.

Utilize-o para acompanhar eventos e métricas personalizadas, monitorizar tempos de resposta e falhas da API, implementar rastreamento distribuído entre serviços, registar exceções com propriedades contextuais e controlar o volume de telemetria com amostragem.

go get github.com/microsoft/ApplicationInsights-Go

Para a documentação do serviço, consulte a visão geral do Application Insights.

Passos seguintes

  • Last updated on