Compartilhar via

Visão geral das bibliotecas do SDK do Azure para Go

O SDK do Azure para Go inclui bibliotecas de gerenciamento e bibliotecas de clientes do plano de dados. Este artigo fornece uma visão geral para que você possa entender quais são as bibliotecas, como elas se encaixam em Azure fluxos de trabalho e para onde ir em seguida para padrões específicos do Go.

Bibliotecas de gerenciamento

Use as bibliotecas de gerenciamento para provisionar, configurar e controlar Azure recursos. Eles se concentram no gerenciamento dos próprios recursos em vez dos dados armazenados dentro deles. As bibliotecas de gerenciamento executam operações do plano de controle, que gerenciam os recursos do Azure e a configuração de serviço. As tarefas típicas incluem:

  • Criando ou atualizando grupos de recursos, redes virtuais ou máquinas virtuais.
  • Configurando configurações de segurança, identidades, políticas de acesso e diagnóstico.
  • Listar, marcar e excluir recursos Azure em uma assinatura.
  • Automatizando operações de implantação, limpeza, conformidade e plataforma.

Os pacotes da biblioteca de gerenciamento têm nomes como armcompute, armnetworke armkeyvault. Use bibliotecas de gerenciamento durante as fases de configuração, configuração e governança de um ciclo de vida do aplicativo. Para obter a documentação detalhada do pacote, pesquise o pacote no pkg.go.dev.

Bibliotecas de cliente

Use as bibliotecas de cliente quando seu aplicativo Go precisar trabalhar com dados ou superfícies de runtime dentro de um serviço de Azure já provisionado. As bibliotecas de cliente executam operações de plano de dados , que funcionam com os dados armazenados ou fluindo por meio de um serviço. As tarefas típicas incluem:

  • Carregar e baixar blobs de uma conta de armazenamento.
  • Enviar e receber mensagens com Barramento de Serviço ou Event Hubs.
  • Ler, gravar ou excluir registros em um banco de dados.
  • Recuperando segredos de Key Vault.
  • Executando consultas ou operações em relação aos recursos provisionados.

Os pacotes de biblioteca do cliente têm nomes como azblob, azstorage, azsecrets, azservicebus e azeventhubs. Use bibliotecas de cliente depois de já ter provisionado o serviço de Azure subjacente usando bibliotecas de gerenciamento. Para obter a documentação detalhada do pacote, pesquise o pacote no pkg.go.dev.

Usando bibliotecas de gerenciamento e cliente

Uma única solução Go pode usar bibliotecas de gerenciamento e cliente nas duas dimensões de controle e dados. Por exemplo, você pode usar uma biblioteca de gerenciamento durante a instalação para criar uma conta de armazenamento (plano de controle) e, em seguida, usar uma biblioteca de clientes no aplicativo para carregar e baixar blobs (plano de dados). Entender a distinção ajuda você a escolher a biblioteca certa para cada tarefa em seu fluxo de trabalho.

Para obter padrões e exemplos específicos do Go para cada plano, consulte estes artigos:

Instalando pacotes Go

Na maioria dos projetos, você instala os pacotes Go para controle de versão e gerenciamento de dependência.

Para instalar um pacote Go, execute o go get comando.

Por exemplo, para instalar o armcompute pacote, execute o seguinte comando:

go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute

Na maioria dos aplicativos Go, instale os seguintes pacotes para autenticação:

  • github.com/Azure/azure-sdk-for-go/sdk/azcore/to
  • github.com/Azure/azure-sdk-for-go/sdk/azidentity

Importando pacotes para seu código Go

Depois de baixar os pacotes, importe-os para seu aplicativo usando a import instrução:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute"
)

Autenticação no Azure

Os aplicativos Go que usam bibliotecas do SDK do Azure devem autenticar-se usando o Microsoft Entra ID com a Biblioteca Azure Identity. A autenticação baseada em token é mais segura e gerenciável do que as cadeias de conexão ou chaves. A credencial recomendada depende de onde o aplicativo é executado: usar identidades gerenciadas para aplicativos hospedados no Azure, credenciais de desenvolvedor ou uma entidade de serviço para desenvolvimento local, e uma entidade de serviço para a maioria dos cenários on-premises.

A opção de autenticação padrão é DefaultAzureCredential, que usa as variáveis de ambiente definidas anteriormente neste artigo. No código Go, crie um azidentity objeto da seguinte maneira:

cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  // handle error
}

Para obter mais informações sobre autenticação, consulte SDK do Azure para autenticação Go.

Criando um cliente de Gerenciamento de Recursos

Depois de obter uma credencial do Azure Identity, crie um cliente para se conectar ao serviço de Azure de destino.

Por exemplo, suponha que você queira se conectar ao serviço Azure Compute. O pacote Compute consiste em um ou mais clientes. Um cliente agrupa um conjunto de APIs relacionadas, fornecendo acesso à sua funcionalidade dentro da assinatura especificada. Você cria um ou mais clientes para acessar as APIs necessárias.

O código a seguir usa o tipo armcompute.NewVirtualMachinesClient para criar um cliente para gerenciar máquinas virtuais:

client, err := armcompute.NewVirtualMachinesClient("<subscription ID>", cred, nil)
if err != nil {
  // handle error
}

Para obter mais informações sobre como gerenciar recursos do Azure com Go, consulte Use o SDK do Azure para Go para operações do plano de controle.

Use o mesmo padrão para se conectar a outros serviços Azure. Por exemplo, instale o pacote armnetwork e crie um cliente virtual para gerenciar recursos de rede virtual.

client, err := armnetwork.NewVirtualNetworksClient("<subscription ID>", cred, nil)
if err != nil {
  // handle error
}

Exemplo de código:

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute"
)

func main() {
    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        // handle error
    }
    client, err := armcompute.NewVirtualMachinesClient("<subscription ID>", cred, nil)
    if err != nil {
        // handle error
    }
}

Para obter mais informações sobre como usar os serviços do SDK do Azure for Go for Azure, consulte Use o SDK do Azure for Go para operações de plano de dados.

Usando o repositório SDK do Azure para Go

Depois de criar uma instância de um cliente, use-o para fazer chamadas à API para seus recursos de Azure. Para cenários de gerenciamento de recursos, a maioria dos casos de uso são operações CRUD (criar, ler, atualizar, excluir).

Para localizar operações para um tipo específico, acesse o repositório GitHub do SDK do Azure para Go. A origem do SDK é organizada no diretório sdk/, com bibliotecas de gerenciamento em sdk/resourcemanager/ e bibliotecas de cliente em pastas específicas do serviço, como sdk/storage/ e sdk/security/keyvault/.

Para localizar a origem de um tipo específico, siga estas etapas:

  1. Vá para o repositório SDK do Azure for Go no GitHub.
  2. Navegue até sdk/resourcemanager/ para bibliotecas de gerenciamento ou sdk/ para bibliotecas de cliente.
  3. Abra a pasta de serviço e, em seguida, a pasta do pacote. Por exemplo, sdk/resourcemanager/compute/armcompute/.
  4. Localize o arquivo de origem que contém o tipo necessário. Os tipos de cliente e seus métodos normalmente estão em arquivos com o nome do cliente, como virtualmachines_client.go.
  5. Leia os comentários do tipo e as assinaturas de método para obter informações de uso.

Você também pode criar a URL diretamente. Por exemplo, para encontrar a fonte de operações do grupo de recursos, navegue até https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/resourcemanager/resources/armresources.

Este exemplo mostra como encontrar a origem para operações de grupo de recursos Azure:

  1. Vá para o repositório SDK do Azure for Go no GitHub.
  2. Navegue até sdk/resourcemanager/resources/armresources/.
  3. Abra resource_groups_client.go para localizar o tipo de ResourceGroupsClient e seu método CreateOrUpdate.
  4. Leia os comentários e parâmetros do método para entender como fazer a chamada à API.

Para obter a documentação de referência gerada, pesquise o pacote em pkg.go.dev.

Operações de longa duração

Algumas operações levam muito tempo para serem concluídas. Para lidar com essas operações, as bibliotecas de gerenciamento fornecem funções que dão suporte a LRO (operações de execução longa) por meio de chamadas assíncronas. Esses nomes de função começam com Begin, como BeginCreate e BeginDelete.

Como essas funções são assíncronas, seu código não é bloqueado enquanto a função termina sua tarefa. Em vez disso, a função retorna um objeto poller imediatamente. Em seguida, seu código chama uma função de enquete síncrona que retorna quando a função assíncrona original é concluída.

O snippet de código a seguir mostra um exemplo desse padrão.

ctx := context.Background()
// Call an asynchronous function to create a client. The return value is a poller object.
poller, err := client.BeginCreate(ctx, "resource_identifier", "additional_parameter")

if err != nil {
    // handle error...
}

// Call the poller object's PollUntilDone function that will block until the poller object
// has been updated to indicate the task has completed.
resp, err = poller.PollUntilDone(ctx, nil)
if err != nil {
    // handle error...
}

// Print the fact that the LRO completed.
fmt.Printf("LRO done")

// Work with the response ("resp") object.

Pontos principais:

  • A PollUntilDone função requer um intervalo de sondagem que especifica a frequência com que deve tentar obter o status. O padrão interval é de 30 segundos se você passar nil para o parâmetro de opções, mas você pode ajustá-lo com base em suas necessidades.
  • O intervalo normalmente é curto. Consulte a documentação do recurso específico do Azure para obter os intervalos recomendados.
  • A seção LRO da página Diretrizes de Design do Go SDK do Azure tem um exemplo mais avançado e diretrizes gerais para LRO.

Para obter mais detalhes sobre padrões, consulte os padrões de uso Common no SDK do Azure for Go.

Próximas etapas

Para obter mais informações sobre autenticação, construção de cliente, operação de execução longa e padrões de passo a passo do serviço, consulte os artigos específicos do plano:

Para obter exemplos, consulte SDK do Azure para exemplos de Go em GitHub.

  • Last updated on