Compartilhar via

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

  • Artigo

Neste artigo, você aprende 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 Blobs do Azure. O artigo supõe que você tenha criado os recursos mostrados em Exemplo: criar Armazenamento do Azure.

Todos os comandos neste artigo funcionam da mesma forma no bash do Linux/macOS e nos shells de comando do Windows, a menos que haja uma observação.

1. Configurar seu ambiente de desenvolvimento

Caso ainda não tenha feito isso, configure um ambiente onde você possa executar esse código. Estas são algumas opções:

2. Instalar pacotes de biblioteca

Em seu arquivo requirements.txt, adicione linhas para os pacotes de biblioteca de clientes que você precisa e salve o arquivo.

azure-storage-blob
azure-identity

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

pip install -r requirements.txt

3. Criar um arquivo para carregar

Crie um arquivo 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.

4. Usar o armazenamento de blobs do código do aplicativo

Esta seção demonstra duas maneiras de acessar dados no contêiner de blob que foi criado em Exemplo: criar Armazenamento do Azure. Para acessar os dados no contêiner de blob, seu aplicativo deve ser capaz de se autenticar no Azure e ser autorizado a acessar os dados no contêiner. Esta seção apresenta duas maneiras de fazer isso:

  • O método sem senha (recomendado) autentica o aplicativo usando DefaultAzureCredential. DefaultAzureCredential é uma credencial encadeada que pode autenticar um aplicativo (ou um usuário) usando uma cadeia de credenciais diferentes, incluindo credenciais de ferramentas de desenvolvimento, princípios de serviços de aplicativos e identidades gerenciadas.

  • O método cadeia de conexão usa uma cadeia de conexão para acessar diretamente a conta de armazenamento.

Pelos motivos a seguir e outros, recomendamos o uso do método sem senha sempre que possível:

  • Uma cadeia de conexão autentica o agente de conexão com a conta de armazenamento em vez de conectar com os recursos individuais dentro dessa conta. Como resultado, uma string de conexão concede uma autorização mais ampla do que o necessário. Com DefaultAzureCredential você pode conceder permissões mais granulares e menos privilegiadas sobre seus recursos de armazenamento para a identidade em que seu aplicativo é executado usando o RBAC do Azure.

  • Uma cadeia de conexão contém informações de acesso em texto sem formatação e, portanto, apresenta possíveis vulnerabilidades se ela estiver construída ou protegida incorretamente. Se essa cadeia de conexão for exposta, ela poderá ser usada para acessar uma ampla gama de recursos na 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 compatíveis DefaultAzureCredential não exigem o armazenamento de segredos em seu ambiente.

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

Nas etapas a seguir, você configura uma entidade de serviço de aplicativo como a identidade do aplicativo. Os princípios de serviço de aplicativo são adequados para uso durante o desenvolvimento local e para aplicativos hospedados no local. Para configurar DefaultAzureCredential o uso da entidade de serviço do aplicativo, 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. Isso é necessário para uma entidade de serviço de aplicativo, mas, dependendo do cenário, você também pode configurar DefaultAzureCredential para usar credenciais que não exigem a configuraçã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 a 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 é alterado.

  1. Crie um arquivo chamado use_blob_auth.py com o seguinte código. Os comentários explicam as etapas.

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

    Links da referência:

  2. Criar uma variável de ambiente com nome AZURE_STORAGE_BLOB_URL:

    set 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. Ela não é usada pelas bibliotecas do Azure.

  3. Use o comando az ad sp create-for-rbac comando para criar uma nova entidade de serviço para o aplicativo. O comando cria o registro do aplicativo para o aplicativo ao mesmo tempo. Dê um nome de sua escolha à entidade de serviço.

    az ad sp create-for-rbac --name <service-principal-name>

    A saída deste comando terá a aparência a seguir. Anote esses valores ou mantenha essa janela aberta, já que você precisará desses valores na próxima etapa e não poderá exibir o valor da senha (segredo do cliente) novamente. Mas você pode adicionar uma nova senha mais tarde, sem invalidar a entidade de serviço ou os segredos 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"
}

    É possível executar os comandos da CLI do Azure no Azure Cloud Shell ou em uma estação de trabalho com a CLI do Azure instalada.

  4. Crie variáveis de ambiente para a entidade de serviço do aplicativo:

    Crie as seguintes variáveis de ambiente com os valores da saída do comando anterior. Essas variáveis dizem ao DefaultAzureCredential para usar a entidade de serviço do aplicativo.

    • AZURE_CLIENT_ID → O valor da ID do aplicativo.
    • AZURE_TENANT_ID → O valor da ID do locatário.
    • AZURE_CLIENT_SECRET → A senha/credencial gerada para o aplicativo.
    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

  5. Tentativa de executar o código (que falha intencionalmente):

    python use_blob_auth.py

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

  7. Conceda permissões de colaborador no contêiner de blob à entidade de serviço usando o comando da CLI do Azure az role assignment create:

    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 o espaço reservado <AZURE_CLIENT_ID> pela ID do aplicativo da entidade de serviço.

    O argumento --scope identifica o local em que essa atribuição de função se aplica. Neste exemplo, você concede a função "Colaborador de Dados de Blob de Armazenamento" à entidade de serviço para o contêiner chamado "blob-container-01".

    • Substitua PythonAzureExample-Storage-rg e pythonazurestorage12345 pelo grupo de recursos que contém sua conta de armazenamento e o nome exato da sua conta de armazenamento. Ajuste o nome do contêiner de blob, se necessário. Se 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 espaço reservado <AZURE_SUBSCRIPTION_ID> pela sua ID de assinatura do Azure. (Você pode executar o comando az account show e obter sua ID de assinatura da propriedade id na saída.)

    Dica

    Se o comando de atribuição de função retornar o erro "Nenhum adaptador de conexão foi encontrado" ao usar o shell bash, tente definir export MSYS_NO_PATHCONV=1 para evitar a conversão de caminho. Para obter mais informações, confira esta edição.

  8. Aguarde alguns minutos para as permissões serem propagadas e execute o código novamente para verificar se ele funciona agora. Se você vir o erro de permissão novamente, aguarde um pouco mais e tente executar o código outra vez.

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

Importante

Nas etapas anteriores, seu aplicativo foi executado em uma entidade de serviço de aplicativo. Uma entidade de serviço de aplicativo requer um segredo do cliente em 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, pode usar credenciais de ferramenta de desenvolvedor, DefaultAzureCredential como as credenciais que você usa para entrar por meio da CLI do Azure; ou, para aplicativos hospedados no Azure, pode usar uma identidade gerenciada. Para saber mais, consulte Autenticar aplicativos Python nos serviços do Azure usando o SDK do Azure para Python.

5. Verificar a criação de blob

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

Página do portal do Azure para o contêiner de blob, mostrando o arquivo carregado

Se tiver criado uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING, você também poderá usar a CLI do Azure para verificar se o blob existe usando o az storage blob list:

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

Se tiver seguido as instruções para usar a autenticação sem senha, você poderá adicionar o parâmetro --connection-string ao comando anterior com a cadeia de conexão para sua 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 toda a cadeia de conexão como o valor do parâmetro --connection-string .

Observação

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

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 você 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 adicionais em sua assinatura, mas recursos, como contas de armazenamento, no grupo de recursos podem continuar a incorrer em encargos. É prática recomendada limpar qualquer grupo que você não esteja usando ativamente. O argumento --no-wait permite que o comando seja retornado imediatamente, em vez de esperar a conclusão da operação.

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

Você também pode usar o método ResourceManagementClient.resource_groups.begin_delete para excluir um grupo de recursos do código. O código em Exemplo: criar um grupo de recursos demonstra o uso.

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

az ad app delete --id <AZURE_CLIENT_ID>

Confira também