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

  • Artigo

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 Blobs 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 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 local

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

2: Instalar pacotes de biblioteca

No arquivo requirements.txt , adicione linhas para o pacote de biblioteca do cliente que você usará e salve o arquivo.

azure-storage-blob
azure-identity

Em seguida, no terminal ou no 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 blob a partir do código do aplicativo

As duas seções a seguir demonstram duas maneiras de acessar o contêiner de blob criado por meio do Exemplo: Criar Armazenamento do Azure.

O primeiro método (com autenticação) autentica o aplicativo com DefaultAzureCredential conforme descrito em Autenticar aplicativos Python para serviços do Azure durante o desenvolvimento local usando entidades de serviço. Com esse método, você deve primeiro atribuir as permissões apropriadas à identidade do aplicativo, que é a prática recomendada.

O segundo método (com cadeia de conexão) usa uma cadeia de conexão para acessar a conta de armazenamento diretamente. Embora esse método pareça mais simples, ele tem duas desvantagens significativas:

  • Uma cadeia de conexão autentica inerentemente o agente de conexão com a conta de armazenamento em vez de conectar com os recursos individuais dentro dessa conta. Como resultado, uma cadeia de conexão concede uma autorização mais ampla do que a necessária.

  • 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 construída ou protegida corretamente. Se essa cadeia de conexão for exposta, ela poderá ser usada para acessar uma ampla variedade de recursos na conta de armazenamento.

Por esses motivos, recomendamos usar o método de autenticação no código de produção.

4a: Usar o armazenamento de blob com autenticação

  1. Crie um arquivo chamadouse_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 AZURE_STORAGE_BLOB_URL variável de ambiente é usada somente por este exemplo. Ele não é usado pelas bibliotecas do Azure.

  3. Use o comando az ad sp create-for-rbac 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ê ao responsável pelo serviço um nome de sua escolha.

    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, pois você precisará desses valores na próxima etapa e não poderá exibir o valor da senha (segredo do cliente) novamente. No entanto, você pode adicionar uma nova senha posteriormente sem invalidar a entidade de serviço ou as senhas existentes, se necessário.

    {
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "{service-principal-name}",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

    É 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 instruem DefaultAzureCredential a 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=00000000-0000-0000-0000-000000000000
set AZURE_TENANT_ID=11111111-1111-1111-1111-111111111111
set AZURE_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz

  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 essa 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 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 --assignee argumento identifica a entidade de serviço. Substitua <AZURE_CLIENT_ID> espaço reservado pelo 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 "Storage Blob Data Contributor" à entidade de serviço do 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 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 espaço reservado AZURE_SUBSCRIPTION_ID <> por sua ID de assinatura do Azure. (Você pode executar o comando az account show e obter sua ID de assinatura da id propriedade na saída.)

    Dica

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

4b: Usar o armazenamento de blob com uma cadeia de conexão

  1. Crie um arquivo Python com o nome use_blob_conn_string.py com o seguinte código. Os comentários explicam as etapas.

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

  2. Crie uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING, o valor que é a cadeia de conexão completa para a conta de armazenamento. (Essa variável de ambiente também é usada por vários comentários da CLI do Azure.) Você pode obter a cadeia de conexão para 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 sua conta de armazenamento e o nome exato da conta de armazenamento.

    Ao definir a variável de ambiente, use o connectionString valor inteiro da propriedade na saída, incluindo as aspas.

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

5. Verifique a criação de blob

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

Azure portal page for the blob container, showing the uploaded file

Se você criou uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING, também poderá 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 você seguiu as instruções para usar o armazenamento de blob com autenticação, poderá adicionar o --connection-string parâmetro ao comando anterior com a cadeia de conexão da sua conta de armazenamento. Para saber como obter a cadeia de conexão, consulte as instruções em 4b: Usar o armazenamento de blob com uma cadeia de conexão. Use toda a cadeia de conexão, incluindo as aspas.

6: Limpar 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 cobranças contínuas em sua assinatura, mas os recursos, como contas de armazenamento, no grupo de recursos podem incorrer em cobranças. É uma boa prática 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 o armazenamento de blob com autenticação, é recomendável 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> pelo ID do aplicativo da entidade de serviço.

az ad app delete --id <AZURE_CLIENT_ID>

Confira também