Partilhar via

Visão geral das bibliotecas SDK do Azure for Go

O SDK do Azure for Go inclui tanto bibliotecas de gestão como bibliotecas de clientes no plano de dados. Este artigo fornece uma visão geral para que possa compreender quais são as bibliotecas, como se encaixam nos fluxos de trabalho do Azure e para onde seguir padrões específicos do Go.

Bibliotecas de gerenciamento

Use as bibliotecas de gestão para provisionar, configurar e governar os recursos do Azure. Focam-se na gestão dos próprios recursos em vez dos dados armazenados no seu interior. As bibliotecas de gestão realizam operações do plano de controlo, que gerem os recursos do Azure e a configuração dos serviços. As tarefas típicas incluem:

  • Criar ou atualizar grupos de recursos, redes virtuais ou máquinas virtuais.
  • Configurar definições de segurança, identidades, políticas de acesso e diagnósticos.
  • Listar, etiquetar e eliminar recursos do Azure através de uma subscrição.
  • Automatização da implementação, limpeza, conformidade e operações de plataforma.

Os pacotes de bibliotecas de gestão têm nomes como armcompute, armnetwork, e armkeyvault. Utilize bibliotecas de gestão durante as fases de preparação, configuração e gestão de uma aplicação. Para documentação detalhada do pacote, pesquise o pacote no pkg.go.dev.

Bibliotecas de cliente

Use as bibliotecas clientes quando a sua aplicação Go precisar de trabalhar com dados ou superfícies de runtime dentro de um serviço Azure já provisionado. As bibliotecas cliente realizam operações no plano de dados , que trabalham com os dados armazenados ou que fluem através de um serviço. As tarefas típicas incluem:

  • Carregar e descarregar blobs a partir de uma conta de armazenamento.
  • Enviar e receber mensagens com Service Bus ou Event Hubs.
  • Ler, escrever ou apagar registos numa base de dados.
  • A recuperar segredos do cofre de chaves.
  • Executar consultas ou operações contra recursos provisionados.

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

Utilização tanto de bibliotecas de gestão como de clientes

Uma única solução Go pode usar tanto bibliotecas de gestão quanto bibliotecas de clientes nos planos de controlo e de dados. Por exemplo, pode usar uma biblioteca de gestão durante a configuração para criar uma conta de armazenamento (plano de controlo) e depois usar uma biblioteca cliente na aplicação para carregar e descarregar blobs (plano de dados). Compreender a distinção ajuda-o a escolher a biblioteca certa para cada tarefa no seu fluxo de trabalho.

Para padrões e exemplos específicos de Go para cada plano, veja 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 das aplicações 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

Importar pacotes para o seu código Go

Depois de descarregar os pacotes, importe-os para a sua aplicação usando a import declaraçã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 ao Azure

As aplicações Go que usam bibliotecas SDK do Azure devem autenticar-se usando Microsoft Entra ID com a biblioteca de identidade Azure Identity. A autenticação baseada em tokens é mais segura e gerível do que cadeias de ligação ou chaves. A credencial recomendada depende de onde a aplicação corre: use identidades geridas para aplicações alojadas no Azure, credenciais de programador ou um principal de serviço para desenvolvimento local, e um principal de serviço para a maioria dos cenários locais.

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

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

Para mais informações sobre autenticação, veja 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 ligar ao serviço Azure alvo.

Por exemplo, suponha que quer ligar-se 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 seguinte utiliza o armcompute. NewVirtualMachinesTipo de cliente para criar um cliente para gerir máquinas virtuais:

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

Para mais informações sobre a gestão de recursos Azure com Go, veja Use o SDK do Azure para Go para operações de plano de controlo.

Use o mesmo padrão para se ligar a outros serviços do Azure. Por exemplo, instale o pacote armnetwork e crie um cliente rede virtual para gerir 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 mais informações sobre a utilização do SDK do Azure para Go para serviços de Azure, veja Use o SDK do Azure para Go para operações de plano de dados.

Utilização do repositório do SDK do Azure for Go

Depois de instanciares um cliente, usa-o para fazer chamadas de API aos teus 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 encontrar operações para um tipo específico, navegue pelo código-fonte no SDK do Azure para o repositório Go GitHub. O código-fonte do SDK está organizado sob o diretório sdk/, com as bibliotecas de gestão sob sdk/resourcemanager/ e as bibliotecas clientes em pastas específicas do serviço, como sdk/storage/ e sdk/security/keyvault/.

Para localizar a fonte de um tipo específico, siga estes passos:

  1. Vai ao repositório SDK do Azure para Go no GitHub.
  2. Navegue para sdk/resourcemanager/ para bibliotecas de gestão, ou para sdk/ para bibliotecas de cliente.
  3. Abra a pasta de serviço e depois a pasta de pacotes. Por exemplo, sdk/resourcemanager/compute/armcompute/.
  4. Encontre o ficheiro de origem que contém o tipo que precisa. Os tipos de cliente e os seus métodos encontram-se tipicamente em ficheiros nomeados em homenagem ao cliente, como virtualmachines_client.go.
  5. Leia os comentários sobre o tipo e as assinaturas dos métodos para obter informações sobre o uso.

Também pode construir o 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 fonte para operações de grupos de recursos do Azure:

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

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

Operações de longa duração

Algumas operações demoram muito tempo a concluir. Para gerir estas operações, as bibliotecas de gestão fornecem funções que suportam operações de longa duração (LRO) através de chamadas assíncronas. Estes nomes de funções começam por 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, o código chama uma função de poller síncrono que retorna quando a função assíncrona original é concluída.

O trecho 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 com que frequência deve tentar obter o status. O intervalo por defeito é 30 segundos se passares nil para o parâmetro de opções, mas podes ajustá-lo conforme as tuas necessidades.
  • O intervalo é normalmente curto. Consulte a documentação do recurso específico do Azure para intervalos recomendados.
  • A secção LRO da página Go SDK do Azure Design Guidelines tem um exemplo mais avançado e diretrizes gerais para LRO.

Para mais detalhes sobre padrões, consulte o Padrões de uso comum em SDK do Azure para Go.

Próximos passos

Para mais informações sobre autenticações, construção de clientes, operações de longa duração e padrões de guia de serviço, consulte os artigos específicos do plano:

Para exemplos, veja SDK do Azure para amostras de Go em GitHub.

  • Last updated on