Exemplo: Acessar o Armazenamento do Azure usando as bibliotecas do Azure para Python

Neste artigo, você aprenderá a usar as bibliotecas de cliente do Azure no código do aplicativo Python para carregar um arquivo em um contêiner de armazenamento de Blob do Azure. O artigo pressupõe que você criou os recursos mostrados em Exemplo: Criar Armazenamento do Azure.

Todos os comandos neste artigo funcionam da mesma forma em shells de comando Linux/macOS bash e Windows, a menos que indicado.

1. Configure o seu ambiente de desenvolvimento local

Se ainda não o fez, configure um ambiente onde possa executar o código. Seguem-se algumas opções:

Configure um ambiente virtual Python usando venv ou sua ferramenta de preferência. Para começar a usar o ambiente virtual, não deixe de ativá-lo. Para instalar o python, consulte Instalar o Python.

Bash
PowerShell

#!/bin/bash
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/Scripts/activate # only required for Windows (Git Bash)

# PowerShell syntax
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
. .\venv\Scripts\Activate.ps1

Use um ambiente conda. Para instalar o Conda, consulte Instalar o Miniconda.
Use um contêiner de desenvolvimento no Visual Studio Code ou GitHub Codespaces.

2. Instalar pacotes de biblioteca

No ficheiro requirements.txt, adicione linhas para o pacote da biblioteca cliente de que necessita e guarde o ficheiro.

azure-storage-blob
azure-identity

Em seguida, no terminal ou prompt de comando, instale os requisitos.

pip install -r requirements.txt

3. Crie um ficheiro para carregar

Crie um ficheiro de origem chamado sample-source.txt. Esse nome de arquivo é o que o código espera.

Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob.

Utilize o armazenamento de blobs a partir do código da aplicação

Esta seção demonstra duas maneiras de aceder a dados no contentor de blobs que criou em Exemplo: Criar Azure Storage. Para acessar dados no contêiner de blob, seu aplicativo deve ser capaz de se autenticar com o Azure e estar autorizado a acessar dados no contêiner. Esta seção apresenta duas maneiras de fazer isso:

O método Passwordless (Recomendado) autentica a aplicação usando DefaultAzureCredential. DefaultAzureCredential é uma credencial encadeada que pode autenticar um aplicativo (ou um utilizador) usando uma sequência de credenciais diferentes, incluindo credenciais de ferramentas de desenvolvimento, entidades de serviço de aplicação e identidades geridas.
O método "Connection string" utiliza uma cadeia de ligação para aceder diretamente à conta de armazenamento.

Pelos seguintes motivos e muito mais, recomendamos o uso do método sem senha sempre que possível:

Uma string de conexão autentica o agente de conexão com a Storage account em vez de recursos individuais dentro dessa conta. Como resultado, uma cadeia de conexão concede uma autorização mais ampla do que seria necessária. Com DefaultAzureCredential pode conceder permissões mais granulares e com o mínimo de privilégios sobre os seus recursos de armazenamento para a identidade sob a qual a sua aplicação funciona utilizando o Controlo de Acesso Baseado em Funções do Azure (Azure RBAC).
Uma cadeia de conexão contém informações de acesso em texto sem formatação e, portanto, apresenta vulnerabilidades potenciais se não for adequadamente construída ou protegida. Se essa cadeia de conexão estiver exposta, ela poderá ser usada para acessar uma ampla gama de recursos dentro da conta de armazenamento.
Uma cadeia de conexão geralmente é armazenada em uma variável de ambiente, o que a torna vulnerável a comprometimento se um invasor obtiver acesso ao seu ambiente. Muitos dos tipos de credenciais suportados por DefaultAzureCredential não exigem o armazenamento de segredos no seu ambiente.

Sem senha (recomendado)
Cadeia de Ligação

DefaultAzureCredential é uma cadeia de credenciais opinativa e pré-configurada. DefaultAzureCredential suporta muitos ambientes, juntamente com os fluxos de autenticação mais comuns e ferramentas de desenvolvedor. Uma instância de DefaultAzureCredential determina quais tipos de credenciais tentar obter um token, com base em uma combinação de seu ambiente de execução em tempo real, no valor de certas variáveis de ambiente bem conhecidas e, opcionalmente, nos parâmetros passados para seu construtor.

Nas etapas a seguir, configura um principal de serviço de aplicação como a identidade da aplicação. As entidades de serviço de aplicativo são adequadas para uso durante o desenvolvimento local e para aplicativos hospedados localmente. Para configurar DefaultAzureCredential para usar o principal de serviço da aplicação, defina as seguintes variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID e AZURE_CLIENT_SECRET.

Observe que um segredo do cliente está configurado. Um segredo de cliente é necessário para um principal de serviço de aplicação, mas, dependendo do seu cenário, também é possível configurar DefaultAzureCredential para usar credenciais que não exigem a definição de um segredo ou senha em uma variável de ambiente.

Por exemplo, no desenvolvimento local, se DefaultAzureCredential não for possível obter um token usando variáveis de ambiente configuradas, ele tentará obter um usando o usuário (já) conectado em ferramentas de desenvolvimento como a CLI do Azure; para um aplicativo hospedado no Azure, DefaultAzureCredential pode ser configurado para usar uma identidade gerenciada. Em todos os casos, o código em seu aplicativo permanece o mesmo, apenas a configuração e/ou o ambiente de tempo de execução são alterados.

Crie um ficheiro chamado use_blob_auth.py com o código a seguir. Os comentários explicam os passos.

import os
import uuid

from azure.identity import DefaultAzureCredential

# Import the client object from the SDK library
from azure.storage.blob import BlobClient

credential = DefaultAzureCredential()

# Retrieve the storage blob service URL, which is of the form
# https://<your-storage-account-name>.blob.core.windows.net/
storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]

# Create the client object using the storage URL and the credential
blob_client = BlobClient(
    storage_url,
    container_name="blob-container-01",
    blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
    credential=credential,
)

# Open a local file and upload its contents to Blob Storage
with open("./sample-source.txt", "rb") as data:
    blob_client.upload_blob(data)
    print(f"Uploaded sample-source.txt to {blob_client.url}")

Ligações de referência:

Crie uma variável de ambiente chamada AZURE_STORAGE_BLOB_URL:
- CMD
- bash
```
set AZURE_STORAGE_BLOB_URL=https://pythonazurestorage12345.blob.core.windows.net
```
```
AZURE_STORAGE_BLOB_URL=https://pythonazurestorage12345.blob.core.windows.net
```
Substitua "pythonazurestorage12345" pelo nome da sua conta de armazenamento.

A variável de ambiente AZURE_STORAGE_BLOB_URL é usada apenas por este exemplo. Ele não é usado pelas bibliotecas do Azure.
Utilize o comando az ad sp create-for-rbac para criar uma nova entidade de serviço para a aplicação. O comando cria, simultaneamente, o registo da aplicação para a aplicação. Dê ao principal de serviço um nome à sua escolha.
```
az ad sp create-for-rbac --name <service-principal-name>
```
A saída deste comando se parece com o seguinte trecho JSON. Anote esses valores ou mantenha essa janela aberta, pois você precisará desses valores na próxima etapa e não poderá visualizar o valor da senha (segredo do cliente) novamente. No entanto, você pode adicionar uma nova senha mais tarde sem invalidar a entidade de serviço ou as senhas existentes, se necessário.
```
{
  "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "displayName": "<service-principal-name>",
  "password": "Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2",
  "tenant": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
```
Os comandos do Azure CLI podem ser executados no Azure Cloud Shell ou numa estação de trabalho com o Azure CLI instalado.
Crie variáveis de ambiente para o principal de serviço da aplicação:

Crie as seguintes variáveis de ambiente com os valores da saída do comando anterior. Essas variáveis dizem DefaultAzureCredential para usar a entidade de serviço do aplicativo.
- AZURE_CLIENT_ID → O valor da ID do aplicativo.
- AZURE_TENANT_ID → O valor do identificador de inquilino.
- AZURE_CLIENT_SECRET → A senha/credencial gerada para o aplicativo.
- CMD
- bash
```
set AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
set AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
set AZURE_CLIENT_SECRET=Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
```
```
AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
AZURE_CLIENT_SECRET=Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
```
Tente executar o código (que falha intencionalmente):
```
python use_blob_auth.py
```
Observe o erro "Esta solicitação não está autorizada a executar esta operação usando esta permissão." O erro é esperado porque a entidade de serviço local que você está usando ainda não tem permissão para acessar o contêiner de blob.
Conceda permissões de Colaborador de Dados de Blob de Armazenamento no contêiner de blob para a entidade de serviço usando o comando az role assignment create Azure CLI:
```
az role assignment create --assignee <AZURE_CLIENT_ID> \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/<AZURE_SUBSCRIPTION_ID>/resourceGroups/PythonAzureExample-Storage-rg/providers/Microsoft.Storage/storageAccounts/pythonazurestorage12345/blobServices/default/containers/blob-container-01"
```
O argumento --assignee identifica a entidade de serviço. Substitua <AZURE_CLIENT_ID> espaço reservado pelo ID da aplicação do principal de serviço.

O argumento --scope identifica onde esta atribuição de função se aplica. Neste exemplo, o utilizador concede a função "Storage Blob Data Contributor" ao principal de serviço do contentor chamado "blob-container-01".
- Substitua PythonAzureExample-Storage-rg e pythonazurestorage12345 pelo grupo de recursos que contém a sua conta de armazenamento e o nome exato da sua conta de armazenamento. Além disso, ajuste o nome do contêiner de blob, se necessário. Se você usar o nome errado, verá o erro "Não é possível executar a operação solicitada no recurso aninhado. Recurso pai 'pythonazurestorage12345' não encontrado."
- Substitua o marcador de posição <AZURE_SUBSCRIPTION_ID> pela sua ID de subscrição do Azure. (Você pode executar o comando az account show e obter o seu ID de assinatura a partir da propriedade id no resultado.)
Gorjeta

Se o comando de atribuição de função retornar um erro "Nenhum adaptador de conexão foi encontrado" ao usar o shell bash, tente configurar export MSYS_NO_PATHCONV=1 para evitar a conversão de caminho. Para obter mais informações, consulte esta questão.
Aguarde um ou dois minutos para que as permissões se propaguem e, em seguida, execute o código novamente para verificar se ele agora funciona. Se você vir o erro de permissões novamente, aguarde um pouco mais e tente o código novamente.

Para obter mais informações sobre atribuições de função, consulte Como atribuir permissões de função usando a Azure CLI.

Importante

Nas etapas anteriores, a sua aplicação foi executada sob um principal de serviço de aplicação. Um principal de serviço de aplicação requer um segredo de cliente na sua configuração. No entanto, você pode usar o mesmo código para executar o aplicativo em diferentes tipos de credenciais que não exigem que você configure explicitamente uma senha ou segredo no ambiente. Por exemplo, durante o desenvolvimento, podem ser utilizadas credenciais de ferramentas de desenvolvimento, como as credenciais usadas para entrar através da CLI do Azure; ou, para aplicações hospedadas no Azure, pode ser utilizada uma identidade gerida. Para saber mais, consulte Autenticar aplicações Python nos serviços do Azure usando o SDK do Azure para Python.

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.

Crie um arquivo Python chamado use_blob_conn_string.py com o código a seguir. Os comentários explicam os passos.

import os
import uuid

# Import the client object from the SDK library
from azure.storage.blob import BlobClient

# Retrieve the connection string from an environment variable. Note that a
# connection string grants all permissions to the caller, making it less
# secure than obtaining a BlobClient object using credentials.
conn_string = os.environ["AZURE_STORAGE_CONNECTION_STRING"]

# Create the client object for the resource identified by the connection
# string, indicating also the blob container and the name of the specific
# blob we want.
blob_client = BlobClient.from_connection_string(
    conn_string,
    container_name="blob-container-01",
    blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
)

# Open a local file and upload its contents to Blob Storage
with open("./sample-source.txt", "rb") as data:
    blob_client.upload_blob(data)
    print(f"Uploaded sample-source.txt to {blob_client.url}")

Crie uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING, cujo valor é a cadeia de conexão completa para a conta de armazenamento. (Essa variável de ambiente também é utilizada por vários comandos da CLI do Azure.) Pode obter a cadeia de ligação para a sua conta de armazenamento executando o comando az storage account show-connection-string.
```
az storage account show-connection-string --resource-group PythonAzureExample-Storage-rg --name pythonazurestorage12345
```
Substitua PythonAzureExample-Storage-rg e pythonazurestorage12345 pelo grupo de recursos que contém a sua conta de armazenamento e o nome exato da sua conta de armazenamento.

Ao definir a variável de ambiente, use todo o valor da propriedade connectionString na saída, incluindo as aspas.
Execute o código:
```
python use_blob_conn_string.py
```

Novamente, embora esse método seja simples, uma cadeia de conexão autoriza todas as operações em uma conta de armazenamento. Com o código de produção, é melhor usar permissões específicas, conforme descrito na seção anterior.

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 funcionalidades e benefícios de segurança aprimorados e é a abordagem recomendada para gerir a autorização de serviços do Azure.

5. Verificar a criação de um blob

Depois de executar o código de qualquer um dos métodos, vá para o portal Azure, navegue até o contentor de blobs para verificar se existe um novo blob chamado sample-blob-{random}.txt com o mesmo conteúdo do ficheiro sample-source.txt:

Azure portal page for the blob container, showing the uploaded file Página do portal do Azure para o contêiner de blob, mostrando o arquivo carregado

Se criar uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING, também pode usar a CLI do Azure para verificar se o blob existe usando o comando az storage blob list :

az storage blob list --container-name blob-container-01

Se seguiram as instruções para usar a autenticação sem senha, podem adicionar o parâmetro --connection-string ao comando anterior com a cadeia de conexão para a vossa conta de armazenamento. Para obter a cadeia de conexão, use o comando az storage account show-connection-string.

az storage account show-connection-string --resource-group PythonAzureExample-Storage-rg --name pythonazurestorage12345 --output tsv

Use a cadeia de conexão inteira como valor para o parâmetro --connection-string.

Nota

Se a sua conta de usuário do Azure tiver a função de "Colaborador de Dados de Blob de Armazenamento" no contentor, pode usar o seguinte comando para listar os blobs no contentor:

az storage blob list --container-name blob-container-01 --account-name pythonazurestorage12345 --auth-mode login

6. Limpar os recursos

Execute o comando az group delete se não precisar manter o grupo de recursos e os recursos de armazenamento usados neste exemplo. Os grupos de recursos não incorrem em encargos contínuos na sua subscrição, mas os recursos, como contas de armazenamento, no grupo de recursos podem continuar a incorrer em encargos. É uma boa prática limpar qualquer grupo que você não esteja usando ativamente. O argumento --no-wait permite que o comando retorne imediatamente em vez de esperar que a operação termine.

az group delete -n PythonAzureExample-Storage-rg  --no-wait

Você também pode usar o ResourceManagementClient.resource_groups.begin_delete método para eliminar um grupo de recursos a partir do código. O código no Exemplo: Criar um grupo de recursos demonstra a utilização.

Se seguiste as instruções para usar a autenticação sem senha, é uma boa ideia excluir o principal de serviço de aplicação que criaste. Você pode usar o az ad app delete comando. Substitua o espaço reservado <AZURE_CLIENT_ID> pelo ID do aplicativo da entidade de serviço.

az ad app delete --id <AZURE_CLIENT_ID>

Consulte também

Comentários

Esta página foi útil?

Last updated on 2025-09-22