Biblioteca de clientes de Blobs de Armazenamento do Azure para Python – versão 12.19.0

Artigo
11/07/2023

O Armazenamento de Blobs do Azure é uma solução de armazenamento de objetos da Microsoft para a nuvem. O armazenamento de Blobs é otimizado para armazenar grandes quantidades de dados não estruturados, como texto ou dados binários.

O armazenamento de Blobs é ideal para:

Fornecer imagens ou documentos diretamente a um navegador
O armazenamento de arquivos para acesso distribuído
Transmitir áudio e vídeo por streaming
O armazenamento de dados para backup e restauração, recuperação de desastre e arquivamento
O armazenamento de dados para análise por um serviço local ou hospedado no Azure

Introdução

Pré-requisitos

É necessário ter o Python 3.7 ou posterior para usar esse pacote. Para obter mais detalhes, leia nossa página sobre a política de suporte da versão do SDK do Azure para Python.
Você deve ter uma assinatura do Azure e uma conta de armazenamento do Azure para usar esse pacote.

Instalar o pacote

Instale a biblioteca de clientes de Blobs de Armazenamento do Azure para Python com pip:

pip install azure-storage-blob

Criar uma conta de armazenamento

Se você quiser criar uma nova conta de armazenamento, poderá usar o Portal do Azure, Azure PowerShell ou a CLI do Azure:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Crie o cliente

A biblioteca de clientes de Blobs de Armazenamento do Azure para Python permite que você interaja com três tipos de recursos: a própria conta de armazenamento, contêineres de armazenamento de blobs e blobs. A interação com esses recursos começa com uma instância de um cliente. Para criar um objeto cliente, você precisará da URL da conta de serviço blob da conta de armazenamento e de uma credencial que permita acessar a conta de armazenamento:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Pesquisando a URL da conta

Você pode encontrar a URL do serviço blob da conta de armazenamento usando o Portal do Azure, Azure PowerShell ou a CLI do Azure:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Tipos de credenciais

O credential parâmetro pode ser fornecido de várias formas diferentes, dependendo do tipo de autorização que você deseja usar:

Para usar uma credencial de token do AAD (Azure Active Directory), forneça uma instância do tipo de credencial desejado obtido da biblioteca azure-identity . Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente.

Isso requer alguma configuração inicial:
- Instalar azure-identity
- Registrar um novo aplicativo do AAD e conceder permissões para acessar o Armazenamento do Azure
- Conceder acesso a dados de Blob do Azure com RBAC no Portal do Azure
- Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET
Use a credencial de token retornada para autenticar o cliente:
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```

Para usar um token SAS (assinatura de acesso compartilhado), forneça o token como uma cadeia de caracteres. Se a URL da conta incluir o token SAS, omita o parâmetro de credencial. Você pode gerar um token SAS do Portal do Azure em "Assinatura de acesso compartilhado" ou usar uma das generate_sas() funções para criar um token sas para a conta de armazenamento, contêiner ou blob:

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

Para usar uma chave compartilhada da conta de armazenamento (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia de caracteres. Isso pode ser encontrado no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI do Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Use a chave como o parâmetro de credencial para autenticar o cliente:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
Se você estiver usando a URL personalizada (o que significa que a URL não está nesse formato <my_account_name>.blob.core.windows.net), crie uma instância do cliente usando a credencial abaixo:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
Para usar o acesso de leitura público anônimo, basta omitir o parâmetro de credencial.

Criando o cliente de um cadeia de conexão

Dependendo do caso de uso e do método de autorização, talvez você prefira inicializar uma instância de cliente com um cadeia de conexão de armazenamento em vez de fornecer a URL da conta e a credencial separadamente. Para fazer isso, passe a cadeia de conexão de armazenamento para o método de classe do from_connection_string cliente:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

A cadeia de conexão com sua conta de armazenamento pode ser encontrada no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Principais conceitos

Os seguintes componentes compõem o Serviço blob do Azure:

A própria conta de armazenamento
Um contêiner dentro da conta de armazenamento
Um blob dentro de um contêiner

A biblioteca de clientes de Blobs de Armazenamento do Azure para Python permite que você interaja com cada um desses componentes por meio do uso de um objeto cliente dedicado.

Clientes

Quatro clientes diferentes são fornecidos para interagir com os vários componentes do Serviço Blob:

BlobServiceClient – esse cliente representa a interação com a própria conta de armazenamento do Azure e permite que você adquira instâncias de cliente pré-configuradas para acessar os contêineres e blobs dentro dele. Ele fornece operações para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir contêineres dentro da conta. Para executar operações em um contêiner ou blob específico, recupere um cliente usando os get_container_client métodos ou get_blob_client .
ContainerClient – esse cliente representa a interação com um contêiner específico (que ainda não precisa existir) e permite que você adquira instâncias de cliente pré-configuradas para acessar os blobs dentro dele. Ele fornece operações para criar, excluir ou configurar um contêiner e inclui operações para listar, carregar e excluir os blobs dentro dele. Para executar operações em um blob específico dentro do contêiner, recupere um cliente usando o get_blob_client método .
BlobClient – esse cliente representa a interação com um blob específico (que ainda não precisa existir). Ele fornece operações para carregar, baixar, excluir e criar instantâneos de um blob, bem como operações específicas por tipo de blob.
BlobLeaseClient – esse cliente representa interações de concessão com um ContainerClient ou BlobClient. Ele fornece operações para adquirir, renovar, liberar, alterar e interromper uma concessão em um recurso especificado.

Clientes assíncronos

Essa biblioteca inclui uma API assíncrona completa com suporte no Python 3.5+. Para usá-lo, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

Os clientes e credenciais assíncronos devem ser fechados quando não forem mais necessários. Esses objetos são gerenciadores de contexto assíncronos e definem métodos assíncronos close .

Tipos de blobs

Depois de inicializar um Cliente, você pode escolher entre os diferentes tipos de blobs:

Blobs de blocos armazenam texto e dados binários, até aproximadamente 4,75 TiB. Os blobs de blocos são compostos por blocos de dados que podem ser gerenciados individualmente
Blobs de acréscimo são compostos de blocos, como blobs de blocos, mas são otimizados para operações de acréscimo. Os blobs de acréscimo são ideais para cenários como registrar dados em log de máquinas virtuais
Os blobs de páginas armazenam arquivos de acesso aleatório de até 8 TiB. Os blobs de página armazenam arquivos VHD (disco rígido virtual) e servem como discos para máquinas virtuais do Azure

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Blob de Armazenamento, incluindo:

Criar um contêiner
Carregando um blob
Baixando um blob
Enumerando blobs

Observe que um contêiner deve ser criado antes de carregar ou baixar um blob.

Criar um contêiner

Crie um contêiner de onde você pode carregar ou baixar blobs.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Usar o cliente assíncrono para carregar um blob

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Carregando um blob

Carregar um blob no contêiner

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Usar o cliente assíncrono para carregar um blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Baixando um blob

Baixar um blob do contêiner

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Baixar um blob de forma assíncrona

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Enumerando blobs

Listar os blobs em seu contêiner

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

Listar os blobs de forma assíncrona

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Configuração opcional

Argumentos palavra-chave opcionais que podem ser passados no nível do cliente e por operação.

Configuração da Política de Repetição

Use os seguintes argumentos palavra-chave ao instanciar um cliente para configurar a política de repetição:

retry_total (int): número total de tentativas a serem permitidas. Tem precedência sobre outras contagens. retry_total=0 Passe se você não quiser repetir as solicitações. O valor padrão é 10.
retry_connect (int): quantos erros relacionados à conexão tentar novamente. O valor padrão é 3.
retry_read (int): quantas vezes tentar novamente em erros de leitura. O valor padrão é 3.
retry_status (int): quantas vezes tentar novamente em códigos de status inválidos. O valor padrão é 3.
retry_to_secondary (bool): se a solicitação deve ser repetida para a secundária, se possível. Isso só deve ser habilitado de contas RA-GRS usadas e dados potencialmente obsoletos podem ser tratados. Assume o padrão de False.

Configuração de criptografia

Use os seguintes argumentos palavra-chave ao instanciar um cliente para configurar a criptografia:

require_encryption (bool): se definido como True, imporá que os objetos sejam criptografados e os descriptografará.
encryption_version (str): especifica a versão da criptografia a ser usada. As opções atuais são '2.0' ou '1.0' e o valor padrão é '1.0'. A versão 1.0 foi preterida e é altamente recomendável usar a versão 2.0.
key_encryption_key (objeto): a chave-criptografia-chave fornecida pelo usuário. A instância deve implementar os seguintes métodos:
- wrap_key(key)--encapsula a chave especificada usando um algoritmo de escolha do usuário.
- get_key_wrap_algorithm()--retorna o algoritmo usado para encapsular a chave simétrica especificada.
- get_kid()--retorna uma ID de chave de cadeia de caracteres para essa chave-criptografia-chave.
key_resolver_function (callable): o resolvedor de chaves fornecido pelo usuário. Usa a cadeia de caracteres kid para retornar uma chave-criptografia-chave implementando a interface definida acima.

Outra configuração de cliente/por operação

Outras configurações opcionais palavra-chave argumentos que podem ser especificados no cliente ou por operação.

Argumentos de palavra-chave do cliente:

connection_timeout (int): o número de segundos que o cliente aguardará para estabelecer uma conexão com o servidor. O padrão é 20 segundos.
read_timeout (int): o número de segundos que o cliente aguardará, entre operações de leitura consecutivas, por uma resposta do servidor. Esse é um tempo limite de nível de soquete e não é afetado pelo tamanho geral dos dados. Os tempos limite de leitura do lado do cliente serão repetidos automaticamente. O padrão é 60 segundos.
transport (Any): transporte fornecido pelo usuário para enviar a solicitação HTTP.

Argumentos de palavra-chave por operação:

raw_response_hook (callable): o retorno de chamada especificado usa a resposta retornada do serviço.
raw_request_hook (callable): o retorno de chamada determinado usa a solicitação antes de ser enviado ao serviço.
client_request_id (str): identificação da solicitação especificada pelo usuário opcional.
user_agent (str): acrescenta o valor personalizado ao cabeçalho user-agent a ser enviado com a solicitação.
logging_enable (bool): habilita o registro em log no nível de DEBUG. Usa False como padrão. Também pode ser passado no nível do cliente para habilitá-lo para todas as solicitações.
logging_body (bool): habilita o registro em log do corpo da solicitação e da resposta. Usa False como padrão. Também pode ser passado no nível do cliente para habilitá-lo para todas as solicitações.
cabeçalhos (dict): passe cabeçalhos personalizados como pares chave e valor. Por exemplo, headers={'CustomValue': value}

Solução de problemas

Geral

Os clientes de Blob de Armazenamento geram exceções definidas no Azure Core.

Essa lista pode ser usada para referência para capturar exceções geradas. Para obter o código de erro específico da exceção, use o error_code atributo , ou seja, exception.error_code.

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. As informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível info.

O log detalhado no nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o logging_enable argumento :

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

service_client.get_service_stats(logging_enable=True)

Próximas etapas

Mais códigos de exemplo

Introdução aos nossos exemplos de Blob.

Vários exemplos do SDK do Python de Blobs de Armazenamento estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com Blobs de Armazenamento:

blob_samples_container_access_policy.py (versão assíncrona) – Exemplos para definir políticas de acesso:
- Configurar a Política de Acesso para contêiner
blob_samples_hello_world.py (versão assíncrona) – exemplos para tarefas comuns do Blob de Armazenamento:
- Configurar um contêiner
- Criar um blob de bloco, página ou acréscimo
- Carregar blobs
- Baixar blobs
- Excluir blobs
blob_samples_authentication.py (versão assíncrona) – exemplos para autenticar e criar o cliente:
- De um cadeia de conexão
- De uma chave de acesso compartilhado
- De um token de assinatura de acesso compartilhado
- Do Active Directory
blob_samples_service.py (versão assíncrona) – exemplos para interagir com o serviço blob:
- Obter Informações da conta
- Obter e definir propriedades de serviço
- Obter estatísticas de serviço
- Criar, listar e excluir contêineres
- Obter o cliente blob ou contêiner
blob_samples_containers.py (versão assíncrona) – exemplos para interagir com contêineres:
- Criar um contêiner e excluir contêineres
- Definir metadados em contêineres
- Obter propriedades de contêiner
- Adquirir uma concessão no contêiner
- Definir uma política de acesso em um contêiner
- Carregar, listar, excluir blobs no contêiner
- Fazer com que o cliente blob interaja com um blob específico
blob_samples_common.py (versão assíncrona) – exemplos comuns a todos os tipos de blobs:
- Criar um instantâneo
- Excluir um instantâneo de blob
- Exclusão temporária de um blob
- Cancelar a exclusão de um blob
- Adquirir uma concessão em um blob
- Copiar um blob de uma URL
blob_samples_directory_interface.py - Exemplos de interfiguração com o Armazenamento de Blobs como se fosse um diretório em um sistema de arquivos:
- Copiar (carregar ou baixar) um único arquivo ou diretório
- Listar arquivos ou diretórios em um único nível ou recursivamente
- Excluir um único arquivo ou excluir recursivamente um diretório

Documentação adicional

Para obter uma documentação mais abrangente sobre o Armazenamento de Blobs do Azure, consulte a documentação do Armazenamento de Blobs do Azure em docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.