Introdução ao Armazenamento de Blobs do Azure e Python

Artigo
10/03/2024

Este artigo mostra como se conectar ao Armazenamento de Blobs do Azure usando a biblioteca de cliente do Armazenamento de Blobs do Azure para Python. Uma vez conectado, use os guias do desenvolvedor para saber como seu código pode operar em contêineres, blobs e recursos do serviço de Armazenamento de Blobs.

Se você deseja começar com um exemplo completo, consulte Guia de início rápido: biblioteca de cliente do Armazenamento de Blobs do Azure para Python.

Pacote de referência | da API (PyPi) | Exemplos de código-fonte | da | biblioteca Dar feedback

Pré-requisitos

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

Configure o seu projeto

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.

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

Em seguida, abra o arquivo de código e adicione as instruções de importação necessárias. Neste exemplo, adicionamos o seguinte ao nosso arquivo .py :

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

Informações da biblioteca do cliente Blob:

azure.storage.blob: contém as classes primárias (objetos de cliente) que você pode usar para operar no serviço, contêineres e blobs.

Programação assíncrona

A biblioteca de cliente do Armazenamento de Blobs do Azure para Python suporta APIs síncronas e assíncronas. As APIs assíncronas são baseadas na biblioteca asyncio do Python.

Siga estas etapas para usar as APIs assíncronas em seu projeto:

Instale um transporte assíncrono, como aiohttp. Você pode instalar aiohttp junto com azure-storage-blob usando um comando opcional dependency install. Neste exemplo, usamos o seguinte pip install comando:
```
pip install azure-storage-blob[aio]
```
Abra o arquivo de código e adicione as instruções de importação necessárias. Neste exemplo, adicionamos o seguinte ao nosso arquivo .py :
```
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
```
A import asyncio instrução só é necessária se você estiver usando a biblioteca em seu código. Ele é adicionado aqui para maior clareza, já que os exemplos nos artigos do guia do desenvolvedor usam a asyncio biblioteca.
Crie um objeto cliente usando async with para começar a trabalhar com recursos de dados. Somente o cliente de nível superior precisa usar async witho , pois outros clientes criados a partir dele compartilham o mesmo pool de conexões. Neste exemplo, criamos um BlobServiceClient objeto usando async witho e, em seguida, criamos um ContainerClient objeto:
```
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    container_client = blob_service_client.get_container_client(container="sample-container")
```
Para saber mais, consulte os exemplos assíncronos em Autorizar acesso e conectar-se ao Armazenamento de Blobs.

Informações da biblioteca do cliente assíncrono de Blob:

azure.storage.blob.aio: contém as classes primárias que você pode usar para operar no serviço, contêineres e blobs de forma assíncrona.

Autorize o acesso e conecte-se ao Armazenamento de Blobs

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância da classe BlobServiceClient . Este objeto é o seu ponto de partida para interagir com recursos de dados no nível da conta de armazenamento. Você pode usá-lo para operar na conta de armazenamento e seus contêineres. Você também pode usar o cliente de serviço para criar clientes de contêiner ou clientes de blob, dependendo do recurso com o qual você precisa trabalhar.

Para saber mais sobre como criar e gerenciar objetos de cliente, incluindo práticas recomendadas, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Você pode autorizar um BlobServiceClient objeto usando um token de autorização do Microsoft Entra, uma chave de acesso de conta ou uma assinatura de acesso compartilhado (SAS). Para uma segurança ideal, a Microsoft recomenda o uso do Microsoft Entra ID com identidades gerenciadas para autorizar solicitações contra dados de blob. Para obter mais informações, consulte Autorizar acesso a blobs usando a ID do Microsoft Entra.

Para autorizar com o Microsoft Entra ID, você precisa usar uma entidade de segurança. O tipo de entidade de segurança de que você precisa depende de onde seu aplicativo é executado. Use a tabela a seguir como guia:

Onde o aplicativo é executado	Principal de segurança	Orientação
Máquina local (desenvolvimento e testes)	Service principal (Principal de serviço)	Para saber como registrar o aplicativo, configurar um grupo do Microsoft Entra, atribuir funções e configurar variáveis de ambiente, consulte Autorizar acesso usando entidades de serviço de desenvolvedor
Máquina local (desenvolvimento e testes)	Identidade do utilizador	Para saber como configurar um grupo do Microsoft Entra, atribuir funções e entrar no Azure, consulte Autorizar acesso usando credenciais de desenvolvedor
Hospedado no Azure	Identidade gerida	Para saber como habilitar a identidade gerenciada e atribuir funções, consulte Autorizar acesso de aplicativos hospedados no Azure usando uma identidade gerenciada
Hospedado fora do Azure (por exemplo, aplicativos locais)	Service principal (Principal de serviço)	Para saber como registrar o aplicativo, atribuir funções e configurar variáveis de ambiente, consulte Autorizar acesso de aplicativos locais usando uma entidade de serviço de aplicativo

Autorizar o acesso usando DefaultAzureCredential

Uma maneira fácil e segura de autorizar o acesso e se conectar ao Armazenamento de Blob é obter um token OAuth criando uma instância DefaultAzureCredential . Em seguida, você pode usar essa credencial para criar um objeto BlobServiceClient .

O exemplo a seguir cria um BlobServiceClient objeto usando DefaultAzureCredential:

def get_blob_service_client_token_credential(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Se o seu projeto usa APIs assíncronas, instancie BlobServiceClient usando async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    # Work with data resources in the storage account

Para usar um token de assinatura de acesso compartilhado (SAS), forneça o token como uma cadeia de caracteres e inicialize um objeto BlobServiceClient . Se o URL da sua conta incluir o token SAS, omita o parâmetro credential.

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Se o seu projeto usa APIs assíncronas, instancie BlobServiceClient usando async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

Para saber mais sobre como gerar e gerenciar tokens SAS, consulte os seguintes artigos:

Nota

Para cenários em que as assinaturas de acesso compartilhado (SAS) são usadas, a Microsoft recomenda o uso de uma SAS de delegação de usuário. Uma SAS de delegação de usuário é protegida com credenciais do Microsoft Entra em vez da chave da conta.

Para usar uma chave compartilhada de conta de armazenamento, forneça a chave como uma cadeia de caracteres e inicialize um objeto BlobServiceClient .

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Você também pode criar um BlobServiceClient objeto usando uma cadeia de conexão.

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

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

    return blob_service_client

Se o seu projeto usa APIs assíncronas, instancie BlobServiceClient usando async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

Para obter informações sobre como obter chaves de conta e diretrizes de práticas recomendadas para gerenciar e proteger adequadamente suas chaves, consulte Gerenciar chaves de acesso de conta de armazenamento.

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.

Compilar a sua aplicação

À medida que você cria aplicativos para trabalhar com recursos de dados no Armazenamento de Blobs do Azure, seu código interage principalmente com três tipos de recursos: contas de armazenamento, contêineres e blobs. Para saber mais sobre esses tipos de recursos, como eles se relacionam entre si e como os aplicativos interagem com os recursos, consulte Compreender como os aplicativos interagem com os recursos de dados do Armazenamento de Blobs.

Os guias a seguir mostram como acessar dados e executar ações específicas usando a biblioteca de cliente do Armazenamento do Azure para Python:

Guia	Description
Configurar uma política de repetição	Implemente políticas de repetição para operações de cliente.
Copiar blobs	Copie um blob de um local para outro.
Criar um contêiner	Crie contêineres de blob.
Crie uma SAS de delegação de utilizador	Crie uma SAS de delegação de usuário para um contêiner ou blob.
Criar e gerenciar concessões de blob	Estabeleça e gerencie um bloqueio em um blob.
Criar e gerenciar concessões de contêiner	Estabeleça e gerencie um bloqueio em um contêiner.
Excluir e restaurar blobs	Exclua blobs e restaure blobs excluídos suavemente.
Excluir e restaurar contêineres	Exclua contêineres e restaure contêineres excluídos por software.
Baixar blobs	Baixe blobs usando cadeias de caracteres, fluxos e caminhos de arquivo.
Localizar blobs usando tags	Defina e recupere tags e use tags para localizar blobs.
Listar blobs	Liste blobs de maneiras diferentes.
Listar contêineres	Liste contêineres em uma conta e as várias opções disponíveis para personalizar uma listagem.
Gerenciar propriedades e metadados (blobs)	Obtenha e defina propriedades e metadados para blobs.
Gerenciar propriedades e metadados (contêineres)	Obtenha e defina propriedades e metadados para contêineres.
Ajuste de desempenho para transferências de dados	Otimize o desempenho para operações de transferência de dados.
Definir ou alterar a camada de acesso de um blob	Defina ou altere a camada de acesso para um blob de bloco.
Carregar blobs	Saiba como carregar blobs usando cadeias de caracteres, fluxos, caminhos de arquivo e outros métodos.

Partilhar via

Introdução ao Armazenamento de Blobs do Azure e Python

Pré-requisitos

Configure o seu projeto

Programação assíncrona

Autorize o acesso e conecte-se ao Armazenamento de Blobs

Autorizar o acesso usando DefaultAzureCredential

Compilar a sua aplicação

Comentários

Recursos adicionais