Compartilhar via

Usar o SDK do Azure para Go para operações de plano de dados

Saiba como interagir com os dados armazenados em serviços Azure programaticamente usando as bibliotecas de clientes do SDK do Azure for Go. Para obter uma introdução de nível superior sobre como as bibliotecas de gerenciamento e as bibliotecas de cliente se encaixam, consulte Overview das bibliotecas de gerenciamento do SDK do Azure for Go. Este artigo se concentra nos padrões do plano de dados do Go que você usa após a existência de um recurso, e faz referência às operações do plano de controle para tarefas de provisionamento e configuração.

Qual é o plano de dados Azure?

O plano de dados Azure é o conjunto de APIs que você usa para interagir com dados dentro de serviços Azure, incluindo carregar blobs, enviar mensagens, consultar bancos de dados e recuperar segredos. Enquanto o painel de controle provisiona e configura recursos, o plano de dados é o que o código do aplicativo chama em runtime. Um fluxo de trabalho comum no Go é usar o código do plano de controle uma vez durante a configuração ou automação e então manter os clientes do plano de dados no caminho do aplicativo que é percorrido todos os dias.

O SDK do Azure para Go expõe o plano de dados por meio de pacotes específicos do serviço, como azblob, azservicebus, azeventhubs, azsecrets e azcosmos. Cada pacote se conecta 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 cadeia de conexão.
  3. Chame métodos no cliente para ler, gravar ou processar dados.
  4. Gerencie os resultados e erros paginados.

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

  • Carregando e baixando arquivos de Armazenamento de Blobs
  • Enviar e receber mensagens com Barramento de Serviço ou Hubs de Eventos
  • Armazenando e consultando documentos no Cosmos DB
  • Recuperando segredos, chaves e certificados de Key Vault
  • Monitorando o desempenho do aplicativo com o Application Insights

Autenticação

As operações do plano de dados dão suporte aos mesmos tipos de credencial do pacote azidentity usado para operações de plano de controle. Todos os tipos de credencial implementam a azcore.TokenCredential interface, para que você possa trocá-los sem alterar o código do cliente.

Os clientes no plano de dados utilizam um ponto de extremidade de serviço (URL ou namespace) e uma credencial, ao invés de uma ID de assinatura.

// 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 dão suporte a cadeias de conexão para ambientes em que 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 em execução no Azure, use a identidade gerenciada. Para desenvolvimento local, DefaultAzureCredential descobre automaticamente credenciais de az login, variáveis de ambiente, ou outras fontes.

Para obter um guia completo sobre tipos de credenciais e práticas recomendadas, consulte Authentication com o SDK do Azure for 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 usa 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 esse mesmo padrão de iteração em todos os pacotes do plano de dados.

Para obter mais detalhes sobre paginação e outros padrões comuns, consulte os padrões de uso comuns no SDK do Azure para Go.

Tratamento de erros

As operações do plano de dados retornam erros estruturados que podem ser inspecionados em busca de 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)
}

Os códigos de erro comuns do plano de dados incluem BlobNotFound, MessageLockLoste SecretNotFoundRequestEntityTooLarge. Verifique a documentação de cada serviço para obter 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 de blob, carregar dados com um tempo limite e verificar. Esse padrão se aplica a todos os clientes do plano de dados. Troque o ponto de extremidade do serviço e o tipo de cliente para adaptá-los ao Barramento de Serviço, Hubs de Eventos, 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 de plano de dados a Armazenamento de Blobs do Azure, um serviço de armazenamento de objetos massivamente escalonável. Esse pacote é o que seu aplicativo usa em runtime para ler e gravar dados. Use o pacote de plano de controle separado armstorage para provisionar contas de armazenamento e contêineres.

Use-o para carregar e baixar arquivos e documentos, listar e gerenciar blobs e contêineres, definir metadados e propriedades de conteúdo, implementar uploads paralelos para arquivos grandes e criar pipelines de processamento de dados.

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

Para começar, consulte Início Rápido: módulo de cliente do Armazenamento de Blobs do Azure para Go.

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

Cosmos DB

O pacote azcosmos fornece acesso de plano de dados a Azure Cosmos DB, um banco de dados multimodelo distribuído globalmente. Use-o para criar aplicativos que precisam de leituras e gravações de baixa latência em qualquer escala.

Use-o para executar operações CRUD em documentos, executar consultas SQL em contêineres, gerenciar estratégias de particionamento para acesso eficiente a dados, manipular a paginação em conjuntos de resultados grandes e executar operações em lotes de vários itens.

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

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

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

Hubs de Eventos

O pacote azeventhubs fornece acesso ao plano de dados ao Hubs de Eventos do Azure - um serviço de ingestão de dados em tempo real para streaming de eventos de alta taxa de transferência.

Use-o para enviar eventos com envio em lote para garantir uma taxa de transferência eficiente, receber e processar eventos usando grupos de consumidores de eventos, gerenciar a atribuição de partição e o ponto de verificação, rotear eventos usando chaves de partição para garantia de ordenação e desenvolver pipelines 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 Hubs de Eventos usando o Go.

Para obter 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 para Azure Key Vault. Esses pacotes que seu aplicativo usa em runtime para recuperar segredos e executar operações criptográficas. Use o pacote separado do plano de controle armkeyvault para provisionar e configurar instâncias do Vault.

Use-os para recuperar e definir segredos (senhas de banco de dados, chaves de API), criar e gerenciar chaves criptográficas para assinatura e criptografia, gerenciar certificados TLS/SSL com renovação automática, acompanhar versões secretas e implementar estratégias de rotação e armazenar segredos em cache para reduzir a latência e as 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 a usar Key Vault, consulte Quickstart: Azure Key Vault biblioteca de clientes de certificado para Go.

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

Barramento de Serviço

O pacote azservicebus fornece acesso de plano de dados a Barramento de Serviço do Azure - um agente de mensagens totalmente gerenciado para comunicação assíncrona confiável.

Use-o para enviar e receber mensagens em filas para comunicação ponto a ponto, publicar e assinar tópicos para padrões de fan-out, enviar lotes de mensagens para taxa de transferência eficiente, agendar mensagens para entrega futura e implementar consumidores de sondagem longa com preenchimento e abandono de mensagens.

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

Para começar a usar o Barramento de Serviço do Azure, consulte Início Rápido: Enviar mensagens e receber mensagens de filas do Barramento de Serviço do Azure (Go).

Para obter 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 Aplicativo Azure Insights – serviço do APM (monitoramento de desempenho de aplicativos) do Azure.

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

go get github.com/microsoft/ApplicationInsights-Go

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

Próximas Etapas 

  • Last updated on