Guia de início rápido: biblioteca de cliente do Armazenamento de Blobs do Azure para Go

Artigo
10/18/2023

Introdução à biblioteca de cliente do Armazenamento de Blobs do Azure para Go para 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 Pacote de código-fonte | da biblioteca (pkg.go.dev)

Pré-requisitos

Subscrição do Azure - crie uma gratuitamente
Conta de armazenamento do Azure - criar uma conta de armazenamento
Ir 1.18+

Configuração

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

Transferir a aplicação de exemplo

O exemplo de aplicação utilizado neste início rápido é uma aplicação Go básica.

Utilize o git para transferir uma cópia da aplicação para o seu ambiente de desenvolvimento.

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

Este comando clona o repositório para a sua pasta local do git. Para abrir o exemplo Go para Armazenamento de Blob, 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 seguinte comando:

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

Autenticar 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 DefaultAzureCredential e a biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em 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, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor a chave de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso é capaz de autorizar solicitações contra a conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir 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 de cliente do Azure Identity para Go. DefaultAzureCredential Suporta vários métodos de autenticação e determina qual método usar em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Para saber mais sobre a ordem e os locais em que DefaultAzureCredential procura credenciais, consulte Visão geral da Biblioteca de Identidades do Azure.

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

Atribuir funções à sua conta de utilizador do Microsoft Entra

Ao desenvolver localmente, certifique-se de que a conta de usuário que está acessando dados de blob tenha as permissões corretas. Você precisará do Storage Blob Data Contributor para ler e gravar dados de blob. Para atribuir essa função a si mesmo, você precisará receber a função de Administrador de Acesso de Usuário ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. Você pode atribuir funções do 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, com escopo para a conta de armazenamento, para seguir o Princípio do Menor Privilégio. Essa prática oferece 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 de Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob em sua conta de armazenamento.

Importante

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

No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.
Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.
Na página Controle de acesso (IAM), selecione a guia Atribuições de função.
Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.
Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure por Storage Blob Data Contributor e selecione o resultado correspondente e, em seguida, escolha Next.
Em Atribuir acesso a, selecione Utilizador, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.
Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.
Selecione Rever + atribuir para ir para a página final e, em seguida, Rever + atribuir novamente para concluir o processo.

Para atribuir uma função no nível de recurso usando a CLI do Azure, primeiro você deve recuperar a id do recurso usando o az storage account show comando. Você pode filtrar as propriedades de saída usando o --query parâmetro.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copie a saída Id do comando anterior. Em seguida, você pode atribuir funções usando o comando az role da CLI do Azure.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Para atribuir uma função no nível de recurso usando o Azure PowerShell, primeiro você deve recuperar a ID do recurso usando o Get-AzResource comando.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copie o Id valor da saída do comando anterior. Em seguida, você pode atribuir funções usando o comando New-AzRoleAssignment no PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Você pode autorizar o acesso aos dados em sua conta de armazenamento usando as seguintes etapas:

Certifique-se de que está autenticado com a mesma conta Microsoft Entra à qual atribuiu a função na sua conta de armazenamento. O exemplo a seguir mostra como autenticar por meio da CLI do Azure:
```
az login
```
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 ao Armazenamento do Azure a partir 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.

Executar o exemplo

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

Cria um objeto cliente autorizado para acesso a dados via 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 seguinte comando:

go run storage-quickstart.go

A saída do aplicativo é semelhante ao exemplo a seguir:

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.

Gorjeta

Também pode utilizar uma ferramenta como o Explorador de Armazenamento do Azure para ver os ficheiros no armazenamento de Blobs. O Explorador de Armazenamento do Azure é uma ferramenta multiplataformas gratuita que lhe permite aceder às informações da sua conta de armazenamento.

Compreender o código de exemplo

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

Autorizar o acesso e criar um objeto 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 cliente, o exemplo de código chama azblob. NewClient com os seguintes valores:

serviceURL - o URL da conta de armazenamento
cred - uma credencial Microsoft Entra obtida através do azidentity módulo
opções - opções do cliente; passar nulo para aceitar os valores padrão

O exemplo de código a seguir cria um objeto 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 contentor

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

Importante

Os nomes dos contentores têm de estar em minúscula. Para saber mais sobre os requisitos de nomenclatura para 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 contentor

O exemplo de código cria uma matriz de bytes 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 para o 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 num contentor

O exemplo de código lista os blobs no contêiner especificado. Este 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)
	}
}

Transferir 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 de repetição fará outras solicitações para restabelecer uma conexão e continuar a leitura. Você pode especificar as opções de repetição do leitor 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())

Clean up resources (Limpar 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óximos passos

Neste guia de início rápido, você aprendeu como carregar, baixar e listar blobs usando o Go.

Para ver os aplicativos de exemplo de armazenamento de Blob, continue para:

Exemplos da biblioteca de Armazenamento de Blobs do Azure para Go

Para saber mais, consulte a biblioteca de cliente do Armazenamento de Blobs do Azure para Go.
Para tutoriais, exemplos, inícios rápidos e outra documentação, visite Azure for Go Developers.