Guia de Início Rápido: biblioteca de clientes do Armazenamento de Blobs do Azure para Go

  • Artigo

Introdução à biblioteca de clientes do Armazenamento de Blobs do Azure para Go a fim de gerenciar blobs e contêineres. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (pkg.go.dev)

Pré-requisitos

Configurando

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Go.

Baixar o aplicativo de exemplo

O aplicativo de exemplo usado neste início rápido é um aplicativo Go básico.

Use o git para baixar uma cópia do aplicativo para seu ambiente de desenvolvimento.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart

Este comando clona o repositório para sua pasta do git local. Para abrir o exemplo do Go para o Armazenamento de Blobs, procure o arquivo chamado storage-quickstart.go.

Instalar os pacotes

Para trabalhar com recursos de blob e contêiner em uma conta de armazenamento, instale o pacote azblob usando o seguinte comando:

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

Para autenticar com o Microsoft Entra ID (recomendado), instale o módulo azidentity usando o comando a seguir:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Autenticar-se no Azure e autorizar o acesso a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar a DefaultAzureCredential biblioteca de clientes do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure no seu código, incluindo o armazenamento de Blob.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor as chaves de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave de conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredential é uma implementação de cadeia de credenciais fornecida pela biblioteca do cliente Azure Identity para Go. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina qual método usar no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Para saber mais sobre o pedido e os locais em que DefaultAzureCredential procura as credenciais, consulte Visão geral da biblioteca de Identidade do Azure.

Por exemplo, o aplicativo pode autenticar usando suas credenciais de entrada da CLI do Azure no desenvolvimento local. Depois de implantando no Azure, seu aplicativo pode usar uma identidade gerenciada. Essa transição entre ambientes não exige nenhuma alteração de código.

Atribuir funções à sua conta de usuário do Microsoft Entra

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados de blob tem as permissões corretas. Você precisará do Colaborador de Dados do Blob de Armazenamento para ler e gravar os dados de blob. Para atribuir essa função a si mesmo, você precisará receber a atribuição da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, no escopo da conta de armazenamento, para seguir o Princípio do Privilégio Mínimo. Essa prática fornece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados do Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob na sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure, mas em casos raros pode levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

    A screenshot showing how to assign a role.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de Dados do Blob de Armazenamento e selecione o resultado correspondente e, em seguida, escolha Avançar.

  6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente seu endereço de email user@domain) e escolha Selecionar na parte inferior do diálogo.

  8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Entrar e conectar o código do aplicativo ao Azure usando DefaultAzureCredential

É possível autorizar o acesso aos dados pela conta de armazenamento usando as seguintes etapas:

  1. Verifique se você está autenticado com a mesma conta do Microsoft Entra à qual a função foi atribuída na sua conta de armazenamento. O exemplo a seguir mostra como autenticar por meio da CLI do Azure:

    az login

  2. Para usar DefaultAzureCredential em um aplicativo Go, instale o módulo azidentity usando o seguinte comando:

    go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

A autenticação da CLI do Azure não é recomendada para aplicativos em execução no Azure. Quando implantado no Azure, você pode usar o mesmo código para autorizar solicitações para o Armazenamento do Azure de um aplicativo em execução no Azure. No entanto, você precisa habilitar a identidade gerenciada em seu aplicativo no Azure e configurar sua conta de armazenamento para permitir que essa identidade gerenciada se conecte. Para obter instruções detalhadas sobre como configurar essa conexão entre os serviços do Azure, consulte o tutorial Autenticação de aplicativos hospedados no Azure.

Para saber mais sobre diferentes métodos de autenticação, confira Autenticação do Azure com o SDK do Azure para Go.

Execute o exemplo

O exemplo de código executa as seguintes ações:

  • Cria um objeto cliente autorizado para acesso a dados por meio de DefaultAzureCredential
  • Cria um contêiner em uma conta de armazenamento
  • Carrega um blob no contêiner
  • Lista os blobs no contêiner
  • Baixa os dados de blob em um buffer
  • Exclui os recursos de blob e contêiner criados pelo aplicativo

Antes de executar o exemplo, abra o arquivo storage-quickstart.go. Substitua <storage-account-name> pelo nome da sua conta de armazenamento do Azure.

Em seguida, execute o aplicativo usando o comando a seguir:

go run storage-quickstart.go

A saída do aplicativo é semelhante ao seguinte exemplo:

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

Quando você pressiona a tecla Enter no prompt, o programa de exemplo exclui os recursos de blob e contêiner criados pelo aplicativo.

Dica

Você também pode usar uma ferramenta como o Gerenciador de Armazenamento do Azure para exibir os arquivos no Armazenamento de Blobs. O Gerenciador de Armazenamento do Azure é uma ferramenta gratuita de multiplataforma que permite que você acesse as informações da sua conta de armazenamento.

Entender o código de exemplo

Em seguida, vamos percorrer o código de exemplo para entender como ele funciona.

Autorizar acesso e criar um objeto de cliente

O trabalho com qualquer recurso do Azure usando o SDK começa com a criação de um objeto cliente. Para criar o objeto de cliente, o exemplo de código chama azblob.NewClient com os seguintes valores:

  • serviceURL – a URL da conta de armazenamento
  • credencial – uma credencial do Microsoft Entra obtida por meio do módulo azidentity
  • opções – opções de cliente; passar zero para aceitar os valores padrão

O exemplo de código a seguir cria um objeto de cliente para interagir com recursos de contêiner e blob em uma conta de armazenamento:

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

client, err := azblob.NewClient(url, credential, nil)
handleError(err)

Criar um contêiner

O exemplo de código cria um novo recurso de contêiner na conta de armazenamento. Se um contêiner com o mesmo nome já existir, um ResourceExistsError será gerado.

Importante

Os nomes de contêiner devem estar em minúsculas. Para saber mais sobre os requisitos de como nomear contêineres e blobs, consulte Nomenclatura e referência de contêineres, blobs e metadados.

O exemplo de código a seguir cria um novo contêiner chamado quickstart-sample-container na conta de armazenamento:

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

Carregar blobs para o contêiner

O exemplo de código cria uma matriz de byte com alguns dados e carrega os dados como um buffer para um novo recurso de blob no contêiner especificado.

O exemplo de código a seguir carrega os dados de blob no contêiner especificado usando o método UploadBuffer:

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

Listar os blobs em um contêiner

O exemplo de código lista os blobs no contêiner especificado. Esse exemplo usa NewListBlobsFlatPager, que retorna um pager para blobs a partir do Marcador especificado. Aqui, usamos um Marcador vazio para iniciar a enumeração desde o início e continuar a paginação até que não haja mais resultados. Esse método retorna nomes de blob em ordem lexicográfica.

O exemplo de código a seguir lista os blobs no contêiner especificado:

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

for pager.More() {
	resp, err := pager.NextPage(context.TODO())
	handleError(err)

	for _, blob := range resp.Segment.BlobItems {
		fmt.Println(*blob.Name)
	}
}

Baixar o blob

O exemplo de código baixa um blob usando o método DownloadStream e cria um leitor de repetição para ler dados. Se uma conexão falhar durante a leitura, o leitor ela fará outras solicitações para restabelecer a conexão e continuar a leitura. Você pode especificar opções de leitor de repetição usando o struct RetryReaderOptions.

O exemplo de código a seguir baixa um blob e grava o conteúdo no console:

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

Limpar os recursos

Se você não precisar mais dos blobs carregados neste início rápido, poderá excluir o blob individual usando o método DeleteBlob ou todo o contêiner e seu conteúdo usando o método DeleteContainer.

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

Próximas etapas

Nesse início rápido você aprendeu a carregar, baixar e listar blobs usando Go.

Para ver os aplicativos de exemplo de armazenamento de blobs, acesse:

Amostras da biblioteca do Armazenamento de Blobs do Azure para Go