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

Artigo
06/18/2024

Conforme explicado no artigo O que é o SDK do Azure para linguagem Go?, o SDK do Azure para linguagem Go contém um conjunto de bibliotecas de cliente e de gerenciamento. As bibliotecas de gerenciamento compartilham muitos recursos, como suporte à Identidade do Azure, pipeline HTTP e tratamento de erros. Você pode encontrar a lista completa das bibliotecas de gerenciamento na página do módulo do SDK do Azure para linguagem Go.

Neste artigo, você aprenderá as etapas básicas de como usar as bibliotecas de gerenciamento para interagir com os recursos do Azure.

Instalando pacotes Go

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

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

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

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

Na maioria dos aplicativos Go, você instala 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 o seu código Go

Depois de baixado, o pacote é importado para o seu aplicativo por meio da instrução import:

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

Autenticando-se no Azure

Para executar o código em uma assinatura do Azure, você precisa se autenticar no Azure. O pacote azidentity dá suporte a várias opções para autenticação no Azure. Essas opções incluem cliente/segredo, certificado e identidade gerenciada.

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

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

Criando um cliente de Gerenciamento de Recursos

Depois de ter uma credencial da Identidade do Azure, crie um cliente para se conectar ao serviço do Azure de destino.

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

No seguinte snippet de código, o tipo armcompute.NewVirtualMachinesClient é usado para criar um cliente a fim de gerenciar máquinas virtuais:

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

O mesmo padrão é usado para se conectar a outros serviços do Azure. Por exemplo, instale o pacote armnetwork e crie um cliente de rede virtual para gerenciar recursos de rede virtual (VNET).

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("SubID", cred, nil)
	if err != nil {
        // handle error
    }
}

Usando a documentação de referência do SDK do Azure para linguagem Go

Depois de criadas as instâncias, os clientes são usados para fazer chamadas à API em seus recursos do Azure. Para cenários de gerenciamento de recursos, a maioria dos casos de uso são operações CRUD (Criar/Ler/Atualizar/Excluir).

Para buscar as operações de um tipo específico, execute as seguintes etapas:

Navegue até a documentação de referência do SDK do Azure para linguagem Go.
Pesquise o pacote na página. (Prensagem; <Ctrl+F> expande automaticamente todos os nós na página para pesquisa.)
Selecione o pacote.
Pesquise o tipo na página do pacote.
Leia a descrição do tipo e as informações sobre o uso dele no seu código Go.

Você também pode criar manualmente a URL adicionando o nome do pacote em github.com/Azure/azure-sdk-for-go/sdk/.

Por exemplo, se você estiver buscando a documentação de referência compute/armcompute, a URL será github.com/Azure/azure-sdk-for-go/sdk/compute/armcompute.

O seguinte exemplo mostra como encontrar a documentação de referência das operações do grupo de recursos do Azure:

Navegue até a documentação de referência principal do SDK do Azure para Go no pkg.go.dev.
Selecione <Ctrl+F> e digite resourcemanager/resources/armresources. Ao digitar o termo de pesquisa, você verá uma correspondência próxima com o pacote resources/armresources .
Selecione o pacote apropriado para o seu aplicativo.
Leia as seções "Introdução" ou busque uma operação específica. Por exemplo, pesquisar o termo "resourcegroupsclient.create" (se você quiser criar um grupo de recursos) leva você à função CreateOrUpdate.
Neste ponto, você pode ler como fazer a chamada à API para criar um grupo de recursos do Azure.

Operações de longa duração

Como algumas operações podem levar muito tempo para serem concluídas, as bibliotecas de gerenciamento contêm funções para dar suporte a LRO (operações de execução prolongada) por meio de chamadas assíncronas. Esses nomes de função começam com Begin. Exemplos desse padrão são BeginCreate e BeginDelete.

Como essas funções são assíncronas, seu código não fica bloqueado até que elas terminem suas tarefas. Em vez disso, a função retorna imediatamente um objeto do tipo instrumento de sondagem. Em seguida, seu código chama uma função poller 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 função PollUntilDone exige um intervalo de sondagem que especifica com que frequência ela deve tentar obter o status.
O intervalo normalmente é curto. Confira a documentação do recurso específico do Azure a fim de ver os intervalos recomendados.
A seção LRO da página Diretrizes de Design do SDK do Azure para Go tem diretrizes gerais e um exemplo mais avançados para LRO.

Próximas etapas

Gerenciar grupos de recursos do Azure

Compartilhar via