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

Nota

A opção Construir do zero orienta você passo a passo pelo processo de criação de um novo projeto, instalação de pacotes, escrita do código e execução de um aplicativo de console básico. Essa abordagem é recomendada se você quiser entender todos os detalhes envolvidos na criação de um aplicativo que se conecta ao Armazenamento de Blobs do Azure. Se preferir automatizar as tarefas de implantação e começar com um projeto concluído, escolha Iniciar com um modelo.

Nota

A opção Iniciar com um modelo usa a CLI do Desenvolvedor do Azure para automatizar tarefas de implantação e inicia você com um projeto concluído. Essa abordagem é recomendada se você quiser explorar o código o mais rápido possível sem passar pelas tarefas de configuração. Se preferir instruções passo a passo para criar o aplicativo, escolha Construir do zero.

Introdução à biblioteca de cliente do Armazenamento de Blobs do Azure para Python para gerenciar blobs e contêineres.

Neste artigo, siga as etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Neste artigo, você usa a CLI do Desenvolvedor do Azure para implantar recursos do Azure e executar um aplicativo de console concluído com apenas alguns comandos.

Documentação | de referência da API Pacote de código-fonte | da biblioteca (PyPi)Amostras |

Este vídeo mostra como começar a usar a biblioteca de cliente do Armazenamento de Blobs do Azure para Python.

As etapas no vídeo também são descritas nas seções a seguir.

Pré-requisitos

• Conta do Azure com uma subscrição ativa - crie uma conta gratuitamente
• Conta de Armazenamento do Azure - criar uma conta de armazenamento
• Python 3.8+

• Subscrição do Azure - crie uma gratuitamente
• Python 3.8+
• CLI do desenvolvedor do Azure

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 Python.

Criar o projeto

Crie um aplicativo Python chamado blob-quickstart.

1. Em uma janela de console (como PowerShell ou Bash), crie um novo diretório para o projeto:

   mkdir blob-quickstart
   

2. Alterne para o diretório blob-quickstart recém-criado:

   cd blob-quickstart
   

Instalar os pacotes

No diretório do projeto, instale pacotes para o Armazenamento de Blobs do Azure e as bibliotecas de cliente do Azure Identity usando o pip install comando. O pacote azure-identity é necessário para conexões sem senha com os serviços do Azure.

pip install azure-storage-blob azure-identity

Configurar a estrutura do aplicativo

No diretório do projeto, siga as etapas para criar a estrutura básica do aplicativo:

1. Abra um novo arquivo de texto no editor de códigos.
2. Adicione import instruções, crie a estrutura para o programa e inclua o tratamento básico de exceções, conforme mostrado abaixo.
3. Salve o novo arquivo como blob_quickstart.py no diretório blob-quickstart .

import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Com a CLI do Desenvolvedor do Azure instalada, você pode criar uma conta de armazenamento e executar o código de exemplo com apenas alguns comandos. Você pode executar o projeto em seu ambiente de desenvolvimento local ou em um DevContainer.

Inicializar o modelo da CLI do Azure Developer e implantar recursos

Em um diretório vazio, siga estas etapas para inicializar o azd modelo, provisionar recursos do Azure e começar a usar o código:

• Clone os ativos do repositório de início rápido do GitHub e inicialize o modelo localmente:

  azd init --template blob-storage-quickstart-python
  

  Ser-lhe-ão solicitadas as seguintes informações:

  • Nome do ambiente: esse valor é usado como um prefixo para todos os recursos do Azure criados pela CLI do Desenvolvedor do Azure. O nome deve ser exclusivo em todas as assinaturas do Azure e deve ter entre 3 e 24 caracteres. O nome pode conter apenas letras minúsculas e números.

• Faça logon no Azure:

  azd auth login
  

• Provisione e implante os recursos no Azure:

  azd up
  

  Ser-lhe-ão solicitadas as seguintes informações:

  • Assinatura: a assinatura do Azure na qual seus recursos são implantados.
  • Local: a região do Azure onde seus recursos são implantados.

  A implantação pode levar alguns minutos para ser concluída. A saída do azd up comando inclui o nome da conta de armazenamento recém-criada, que você precisará mais tarde para executar o código.

Execute o código de exemplo

Neste ponto, os recursos são implantados no Azure e o código está quase pronto para ser executado. Siga estas etapas para instalar pacotes, atualizar o nome da conta de armazenamento no código e executar o aplicativo de console de exemplo:

• Instalar pacotes: no diretório local, instale pacotes para as bibliotecas de cliente do Armazenamento de Blobs do Azure e do Azure Identity usando o seguinte comando: pip install azure-storage-blob azure-identity
• Atualize o nome da conta de armazenamento: no diretório local, edite o arquivo chamado blob_quickstart.py. Localize o espaço reservado <storage-account-name> e substitua-o pelo nome real da conta de armazenamento criada pelo azd up comando. Guarde as alterações.
• Execute o projeto: Execute o seguinte comando para executar o aplicativo: python blob_quickstart.py.
• Observe a saída: Este aplicativo cria um arquivo de teste em sua pasta de dados local e o carrega em um contêiner na conta de armazenamento. O exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos antigos e novos.

Para saber mais sobre como o código de exemplo funciona, consulte Exemplos de código.

Quando terminar de testar o código, consulte a seção Limpar recursos para excluir os recursos criados pelo azd up comando.

Modelo de objeto

O Armazenamento de Blobs do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Os dados não estruturados são dados que não seguem uma definição ou um modelo de dados particular, como texto ou dados binários. O armazenamento de Blob oferece três tipos de recursos:

• A conta de armazenamento
• Um contêiner na conta de armazenamento
• Uma bolha no recipiente

O diagrama a seguir mostra a relação entre esses recursos:

Use as seguintes classes Python para interagir com esses recursos:

• BlobServiceClient: A BlobServiceClient classe permite manipular recursos de Armazenamento do Azure e contêineres de blob.
• ContainerClient: A ContainerClient classe permite manipular contêineres de Armazenamento do Azure e seus blobs.
• BlobClient: A BlobClient classe permite manipular blobs de Armazenamento do Azure.

Exemplos de código

Estes trechos de código de exemplo mostram como executar as seguintes tarefas com a biblioteca de cliente do Armazenamento de Blobs do Azure para Python:

• Autenticar no Azure e autorizar o acesso a dados de blob
• Criar um contêiner
• Carregar blobs para um contêiner
• Listar os blobs em um contêiner
• Baixar blobs
• Eliminar um contentor

Nota

O modelo da CLI do Desenvolvedor do Azure inclui um arquivo com código de exemplo já instalado. Os exemplos a seguir fornecem detalhes para cada parte do código de exemplo. O modelo implementa o método de autenticação sem senha recomendado, conforme descrito na seção Autenticar no Azure . O método de cadeia de conexão é mostrado como uma alternativa, mas não é usado no modelo e não é recomendado para código de produção.

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 a DefaultAzureCredential classe fornecida pela 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.

Sem senha (recomendado)

DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado 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.

A ordem e os locais em que DefaultAzureCredential procura credenciais podem ser encontrados na 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. Seu aplicativo pode usar uma identidade gerenciada depois de implantado no Azure. Não são necessárias alterações de código para esta transição.

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 tem 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.

Portal do Azure

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.

   

5. 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.

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

7. 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.

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

CLI do Azure

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

PowerShell

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>

Entre e conecte o código do seu aplicativo ao Azure usando DefaultAzureCredential

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

1. Certifique-se de que está autenticado com a mesma conta Microsoft Entra à qual atribuiu a função na sua conta de armazenamento. Você pode autenticar por meio da CLI do Azure, do Visual Studio Code ou do Azure PowerShell.

   CLI do Azure

   Entre no Azure por meio da CLI do Azure usando o seguinte comando:

   az login
   

   Visual Studio Code

   Você precisará instalar a CLI do Azure para trabalhar com DefaultAzureCredential o Visual Studio Code.

   No menu principal do Visual Studio Code, navegue até Terminal > New Terminal.

   Entre no Azure por meio da CLI do Azure usando o seguinte comando:

   az login
   

   PowerShell

   Entre no Azure usando o PowerShell por meio do seguinte comando:

   Connect-AzAccount
   

2. Para usar DefaultAzureCredentialo , verifique se o pacote azure-identity está instalado e se a classe é importada:

   from azure.identity import DefaultAzureCredential
   from azure.storage.blob import BlobServiceClient
   

3. Adicione este código dentro do try bloco . Quando o código é executado em sua estação de trabalho local, DefaultAzureCredential usa as credenciais de desenvolvedor da ferramenta priorizada na qual você está conectado para autenticar no Azure. Exemplos dessas ferramentas incluem a CLI do Azure ou o Visual Studio Code.

   account_url = "https://<storageaccountname>.blob.core.windows.net"
   default_credential = DefaultAzureCredential()
   
   # Create the BlobServiceClient object
   blob_service_client = BlobServiceClient(account_url, credential=default_credential)
   

4. Certifique-se de atualizar o nome da conta de armazenamento no URI do seu BlobServiceClient objeto. O nome da conta de armazenamento pode ser encontrado na página de visão geral do portal do Azure.

   

   Nota

   Quando implantado no Azure, esse mesmo código pode ser usado para autorizar solicitações ao Armazenamento do Azure a partir de um aplicativo em execução no Azure. No entanto, você precisará habilitar a identidade gerenciada em seu aplicativo no Azure. Em seguida, configure 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.

Cadeia de Ligação

Uma cadeia de conexão inclui a chave de acesso da conta de armazenamento e a usa para autorizar solicitações. Tenha sempre cuidado para nunca expor as chaves num local inseguro.

Nota

Para autorizar o acesso a dados com a chave de acesso da conta de armazenamento, você precisará de permissões para a seguinte ação do RBAC do Azure: Microsoft.Storage/storageAccounts/listkeys/action. A função interna menos privilegiada com permissões para essa ação é Leitor e Acesso a Dados, mas qualquer função que inclua essa ação funcionará.

Portal do Azure

1. Inicie sessão no portal do Azure.

2. Localize a sua conta de armazenamento.

3. No painel de menu da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, você pode visualizar as chaves de acesso da conta e a cadeia de conexão completa para cada chave.

4. No painel Teclas de acesso, selecione Mostrar chaves.

5. Na seção key1, localize o valor da cadeia de conexão. Selecione o ícone Copiar para a área de transferência para copiar a cadeia de conexão. Você adicionará o valor da cadeia de conexão a uma variável de ambiente na próxima seção.

   

CLI do Azure

Você pode ver a cadeia de conexão para sua conta de armazenamento usando o comando az storage account show-connection-string .

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Você pode montar uma cadeia de conexão com o PowerShell usando os comandos Get-AzStorageAccount e Get-AzStorageAccountKey .

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Configurar a cadeia de ligação de armazenamento

Depois de copiar a cadeia de conexão, escreva-a em uma nova variável de ambiente na máquina local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela da consola e siga as instruções relevantes para o seu sistema operativo. Substitua <yourconnectionstring> pela cadeia de conexão real.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Depois de adicionar a variável de ambiente no Windows, você deve iniciar uma nova instância da janela de comando.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

O código abaixo recupera a cadeia de conexão para a conta de armazenamento da variável de ambiente criada anteriormente e usa a cadeia de conexão para construir um objeto de cliente de serviço.

Adicione este código dentro do try bloco:

# Retrieve the connection string for use with the application. The storage
# connection string is stored in an environment variable on the machine
# running the application called AZURE_STORAGE_CONNECTION_STRING. If the environment variable is
# created after the application is launched in a console or with Visual Studio,
# the shell or application needs to be closed and reloaded to take the
# environment variable into account.
connect_str = os.getenv('AZURE_STORAGE_CONNECTION_STRING')

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient.from_connection_string(connect_str)

Importante

A chave de acesso à conta deve ser usada com cuidado. Se a chave de acesso da sua conta for perdida ou acidentalmente colocada num local inseguro, o seu serviço poderá ficar vulnerável. 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 fornece recursos e benefícios de segurança aprimorados e é a abordagem recomendada para gerenciar a autorização para serviços do Azure.

Criar um contentor

Crie um novo contêiner em sua conta de armazenamento chamando o método create_container no blob_service_client objeto. Neste exemplo, o código acrescenta um valor GUID ao nome do contêiner para garantir que ele seja exclusivo.

Adicione este código ao final do try bloco:

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

Para saber mais sobre como criar um contêiner e explorar mais exemplos de código, consulte Criar um contêiner de blob com Python.

Importante

Os nomes dos contentores têm de estar em minúscula. Para obter mais informações sobre a atribuição de nomes de contentores e blobs, veja Nomenclatura e Referenciação de Contentores, Blobs e Metadados.

Carregar blobs para um contêiner

Carregue um blob para um contêiner usando upload_blob. O código de exemplo cria um arquivo de texto no diretório de dados local para carregar no contêiner.

Adicione este código ao final do try bloco:

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Para saber mais sobre como carregar blobs e explorar mais exemplos de código, consulte Carregar um blob com Python.

Listar os blobs num contentor

Liste os blobs no contêiner chamando o método list_blobs . Nesse caso, apenas um blob foi adicionado ao contêiner, portanto, a operação de listagem retorna apenas esse blob.

Adicione este código ao final do try bloco:

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

Para saber mais sobre como listar blobs e explorar mais exemplos de código, consulte Listar blobs com Python.

Transferir blobs

Baixe o blob criado anteriormente chamando o método download_blob . O código de exemplo adiciona um sufixo de "DOWNLOAD" ao nome do arquivo para que você possa ver ambos os arquivos no sistema de arquivos local.

Adicione este código ao final do try bloco:

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

Para saber mais sobre como baixar blobs e explorar mais exemplos de código, consulte Baixar um blob com Python.

Eliminar um contentor

O código a seguir limpa os recursos que o aplicativo criou removendo o contêiner inteiro usando o método delete_container . Você também pode excluir os arquivos locais, se quiser.

O aplicativo pausa para entrada do usuário chamando input() antes de excluir o blob, o contêiner e os arquivos locais. Verifique se os recursos foram criados corretamente antes de serem excluídos.

Adicione este código ao final do try bloco:

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

Para saber mais sobre como excluir um contêiner e explorar mais exemplos de código, consulte Excluir e restaurar um contêiner de blob com Python.

Executar o código

Este aplicativo cria um arquivo de teste em sua pasta local e o carrega no Armazenamento de Blobs do Azure. O exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome. Você pode comparar os arquivos antigos e novos.

Navegue até o diretório que contém o arquivo blob_quickstart.py e execute o seguinte python comando para executar o aplicativo:

python blob_quickstart.py

A saída do aplicativo é semelhante ao exemplo a seguir (valores UUID omitidos para legibilidade):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Antes de iniciar o processo de limpeza, verifique a pasta de dados para os dois arquivos. Você pode compará-los e observar que eles são idênticos.

Clean up resources (Limpar recursos)

Depois de verificar os arquivos e concluir o teste, pressione a tecla Enter para excluir os arquivos de teste junto com o contêiner criado na conta de armazenamento. Você também pode usar a CLI do Azure para excluir recursos.

Quando terminar o início rápido, você poderá limpar os recursos criados executando o seguinte comando:

azd down

Você será solicitado a confirmar a exclusão dos recursos. Entre y para confirmar.

Próximo passo

Exemplos de Armazenamento do Azure e guias do desenvolvedor para Python