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

Artigo
11/07/2023

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

O armazenamento de blobs é ideal para:

Entrega de imagens ou documentos diretamente a um browser
Armazenamento de ficheiros para acesso distribuído
Transmissão de áudio e vídeo
Armazenamento de dados de cópia de segurança e restauro, recuperação após desastre e arquivo
Armazenamento de dados para análise por um serviço no local ou alojado no Azure

Introdução

Pré-requisitos

O Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, leia a nossa página sobre a política de suporte de versões do Azure SDK para Python.
Tem de ter uma subscrição do Azure e uma conta de armazenamento do Azure para utilizar este pacote.

Instalar o pacote

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

pip install azure-storage-blob

Criar uma conta de armazenamento

Se quiser criar uma nova conta de armazenamento, pode utilizar o Portal do Azure, o 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

Criar o cliente

A biblioteca de cliente dos Blobs de Armazenamento do Azure para Python permite-lhe interagir com três tipos de recursos: a própria conta de armazenamento, os contentores de armazenamento de blobs e os blobs. A interação com estes recursos começa com uma instância de um cliente. Para criar um objeto de cliente, precisará do URL da conta de serviço de blobs da conta de armazenamento e de uma credencial que lhe permita aceder à conta de armazenamento:

from azure.storage.blob import BlobServiceClient

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

Procurar o URL da conta

Pode encontrar o URL do serviço de blobs da conta de armazenamento com o Portal do Azure, o 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 em várias formas diferentes, consoante o tipo de autorização que pretende utilizar:

Para utilizar uma credencial de token do Azure Active Directory (AAD), forneça uma instância do tipo de credencial pretendido obtido a partir da biblioteca de identidades do azure . Por exemplo, DefaultAzureCredential pode ser utilizado para autenticar o cliente.

Isto requer alguma configuração inicial:
- Instalar azure-identity
- Registar uma nova aplicação do AAD e dar permissões para aceder ao Armazenamento do Azure
- Conceder acesso a dados de Blobs do Azure com RBAC no portal do Azure
- Defina os valores do ID de cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
Utilize a credencial do token devolvido 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 utilizar um token de assinatura de acesso partilhado (SAS), forneça o token como uma cadeia. Se o URL da conta incluir o token de SAS, omita o parâmetro de credencial. Pode gerar um token de SAS a partir do Portal do Azure em "Assinatura de acesso partilhado" ou utilizar uma das generate_sas() funções para criar um token sas para a conta de armazenamento, contentor 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 utilizar uma chave partilhada da conta de armazenamento (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia. Isto pode ser encontrado no Portal do Azure na secção "Chaves de Acesso" ou ao executar o seguinte comando da CLI do Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Utilize 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 estiver a utilizar o URL personalizado (o que significa que o URL não está neste formato <my_account_name>.blob.core.windows.net), instanciar o cliente com 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 utilizar o acesso de leitura público anónimo, basta omitir o parâmetro de credencial.

Criar o cliente a partir de um cadeia de ligação

Consoante o seu caso de utilização e o método de autorização, pode preferir inicializar uma instância de cliente com um cadeia de ligação de armazenamento em vez de fornecer o URL e a credencial da conta separadamente. Para tal, transmita o cadeia de ligaçã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)

O cadeia de ligação para a sua conta de armazenamento pode ser encontrado no Portal do Azure na secção "Chaves de Acesso" ou ao executar o seguinte comando da CLI:

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

Conceitos-chave

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

A própria conta de armazenamento
Um contentor na conta de armazenamento
Um blob dentro de um contentor

A biblioteca de cliente dos Blobs de Armazenamento do Azure para Python permite-lhe interagir com cada um destes componentes através da utilização de um objeto de cliente dedicado.

Clientes

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

BlobServiceClient – este cliente representa a interação com a própria conta de armazenamento do Azure e permite-lhe adquirir instâncias de cliente pré-configuradas para aceder aos contentores e blobs no mesmo. Fornece operações para obter e configurar as propriedades da conta, bem como listar, criar e eliminar contentores na conta. Para realizar operações num contentor ou blob específico, obtenha um cliente com os get_container_client métodos ou get_blob_client .
ContainerClient – este cliente representa a interação com um contentor específico (que ainda não precisa de existir) e permite-lhe adquirir instâncias de cliente pré-configuradas para aceder aos blobs no mesmo. Fornece operações para criar, eliminar ou configurar um contentor e inclui operações para listar, carregar e eliminar os blobs no mesmo. Para realizar operações num blob específico no contentor, obtenha um cliente com o get_blob_client método .
BlobClient – este cliente representa a interação com um blob específico (que ainda não precisa de existir). Fornece operações para carregar, transferir, eliminar e criar instantâneos de um blob, bem como operações específicas por tipo de blob.
BlobLeaseClient – este cliente representa interações de concessão com um ContainerClient ou BlobClient. Fornece operações para adquirir, renovar, libertar, alterar e interromper uma concessão num recurso especificado.

Clientes Assíncrono

Esta biblioteca inclui uma API assíncrona completa suportada no Python 3.5 e superior. Para utilizá-lo, primeiro tem de instalar um transporte assíncrono, como o aiohttp. Veja a documentação do azure-core para obter mais informações.

Os clientes assíncrono e as credenciais devem ser fechados quando já não forem necessários. Estes objetos são gestores de contexto assíncrono e definem métodos assíncronos close .

Tipos de Blobs

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

Os 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 geridos individualmente
Os blobs de acréscimo são compostos por 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 o registo de dados de máquinas virtuais
Os blobs de páginas armazenam ficheiros de acesso aleatório até 8 TiB de tamanho. Os blobs de páginas armazenam ficheiros de disco rígido virtual (VHD) e servem como discos para máquinas virtuais do Azure

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns do Blob de Armazenamento, incluindo:

Criar um contentor
Carregar um blob
Transferir um blob
Enumerar blobs

Tenha em atenção que um contentor tem de ser criado antes de carregar ou transferir um blob.

Criar um contentor

Crie um contentor a partir do qual pode carregar ou transferir blobs.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Utilizar 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()

Carregar um blob

Carregar um blob para o contentor

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)

Utilizar 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)

Transferir um blob

Transferir um blob a partir do contentor

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)

Transferir 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)

Enumerar blobs

Listar os blobs no contentor

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 de palavra-chave opcionais que podem ser transmitidos ao nível do cliente e por operação.

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

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

retry_total (int): número total de tentativas a permitir. Tem precedência sobre outras contagens. retry_total=0 Transmita se não quiser repetir os pedidos. A predefinição é 10.
retry_connect (int): quantos erros relacionados com a ligação deve repetir. A predefinição é 3.
retry_read (int): quantas vezes repetir erros de leitura. A predefinição é 3.
retry_status (int): quantas vezes tentar novamente códigos de estado incorretos. A predefinição é 3.
retry_to_secondary (bool): se o pedido deve ser repetido para secundário, se possível. Só deve ser ativada a utilização de contas RA-GRS e podem ser processados dados potencialmente obsoletos. A predefinição é False.

Configuração de encriptação

Utilize os seguintes argumentos de palavra-chave ao instanciar um cliente para configurar a encriptação:

require_encryption (bool): se definido como Verdadeiro, irá impor que os objetos são encriptados e desencriptá-los.
encryption_version (str): especifica a versão da encriptação a utilizar. As opções atuais são '2.0' ou '1.0' e o valor predefinido é '1.0'. A versão 1.0 foi preterida e é altamente recomendado utilizar a versão 2.0.
key_encryption_key (objeto): a chave-encriptação-chave fornecida pelo utilizador. A instância tem de implementar os seguintes métodos:
- wrap_key(key)--encapsula a chave especificada com um algoritmo à escolha do utilizador.
- get_key_wrap_algorithm()--devolve o algoritmo utilizado para moldar a chave simétrica especificada.
- get_kid()--devolve um ID de chave de cadeia para esta chave-encriptação-chave.
key_resolver_function (callable): a resolução de chaves fornecida pelo utilizador. Utiliza a cadeia de carateres para devolver uma chave-chave-encriptação que implementa a interface definida acima.

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

Outros argumentos de palavra-chave de configuração opcionais 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 ligação ao servidor. A predefinição é 20 segundos.
read_timeout (int): o número de segundos que o cliente aguardará, entre operações de leitura consecutivas, para obter uma resposta do servidor. Este é um tempo limite ao nível do socket e não é afetado pelo tamanho geral dos dados. Os tempos limite de leitura do lado do cliente serão repetidos automaticamente. A predefinição é 60 segundos.
transporte (Qualquer): transporte fornecido pelo utilizador para enviar o pedido HTTP.

Argumentos de palavra-chave por operação:

raw_response_hook (callable): a chamada de retorno especificada utiliza a resposta devolvida pelo serviço.
raw_request_hook (callable): a chamada de retorno especificada utiliza o pedido antes de ser enviado para o serviço.
client_request_id (str): identificação especificada pelo utilizador opcional do pedido.
user_agent (str): acrescenta o valor personalizado ao cabeçalho user-agent a ser enviado com o pedido.
logging_enable (bool): ativa o registo ao nível de DEBUG. A predefinição é Falso. Também pode ser transmitido ao nível do cliente para ativá-lo para todos os pedidos.
logging_body (bool): ativa o registo do pedido e do corpo da resposta. A predefinição é Falso. Também pode ser transmitido ao nível do cliente para ativá-lo para todos os pedidos.
cabeçalhos (dict): transmita cabeçalhos personalizados como chave, pares de valor. Por exemplo, headers={'CustomValue': value}

Resolução de problemas

Geral

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

Esta lista pode ser utilizada para referência para detetar exceções emitidas. Para obter o código de erro específico da exceção, utilize o error_code atributo , ou seja, exception.error_code.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo detalhado ao nível da DEBUG, incluindo os corpos de pedido/resposta e os cabeçalhos não retotados, pode ser ativado num 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 ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

service_client.get_service_stats(logging_enable=True)

Passos seguintes

Mais código de exemplo

Comece a utilizar os nossos exemplos de Blobs.

Estão disponíveis vários exemplos do SDK Python de Blobs de Armazenamento no repositório do GitHub do SDK. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente 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 o contentor
blob_samples_hello_world.py (versão assíncrona) – exemplos para tarefas comuns do Blob de Armazenamento:
- Configurar um contentor
- Criar um bloco, página ou blob de acréscimo
- Carregar blobs
- Transferir blobs
- Eliminar blobs
blob_samples_authentication.py (versão assíncrona) – exemplos para autenticar e criar o cliente:
- A partir de um cadeia de ligação
- A partir de uma chave de acesso partilhado
- A partir de um token de assinatura de acesso partilhado
- A partir 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 do serviço
- Obter estatísticas de serviço
- Criar, listar e eliminar contentores
- Obter o cliente blob ou contentor
blob_samples_containers.py (versão assíncrona) – exemplos para interagir com contentores:
- Criar um contentor e eliminar contentores
- Definir metadados em contentores
- Obter propriedades do contentor
- Adquirir uma concessão no contentor
- Definir uma política de acesso num contentor
- Carregar, listar, eliminar blobs no contentor
- Obter o cliente de blobs para interagir 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
- Eliminar um instantâneo de blob
- Eliminar um blob de forma recuperável
- Anular a eliminação de um blob
- Adquirir uma concessão num blob
- Copiar um blob de um URL
blob_samples_directory_interface.py - Exemplos para interagir com o armazenamento de Blobs como se fosse um diretório num sistema de ficheiros:
- Copiar (carregar ou transferir) um único ficheiro ou diretório
- Listar ficheiros ou diretórios num único nível ou recursivamente
- Eliminar um único ficheiro ou eliminar recursivamente um diretório

Documentação adicional

Para obter uma documentação mais extensa sobre o armazenamento de Blobs do Azure, veja a documentação do Armazenamento de Blobs do Azure sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.