Compartilhar via

Criar e gerenciar concessões de blob com Python

  • Artigo

Esse artigo mostra como criar e gerenciar concessões de blob usando a biblioteca de clientes do Armazenamento do Azure para Python. Você pode usar a biblioteca de clientes para adquirir, renovar, liberar e interromper concessões de blob.

Para saber mais sobre a concessão de um blob usando APIs assíncronas, consulte Concessão de blobs de forma assíncrona.

Pré-requisitos

  • Este artigo pressupõe que você já tenha um projeto configurado para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Python. Para saber mais sobre como configurar seu projeto, incluindo a instalação de pacote, a adição de instruções de import e a criação de um objeto de cliente autorizado, consulte Introdução ao Armazenamento de Blobs do Azure e Python.
  • O mecanismo de autorização deve ter permissões para trabalhar com tempo de concessão de blob. Para saber mais, consulte as diretrizes de autorização para as seguintes operações de API REST:

Sobre concessões de blob

Uma concessão cria e gerencia um bloqueio em um blob para operações de gravação e exclusão. A duração do bloqueio pode ser de 15 a 60 segundos, ou pode ser infinita. Uma concessão em um blob fornece acesso de gravação e exclusão exclusivo ao blob. Para gravar em um blob com uma concessão ativa, um cliente deverá incluir a ID da concessão ativa com a solicitação de gravação.

Para saber mais sobre os estados de concessão e quando você pode executar uma determinada ação em uma concessão, confira Estados e ações de concessão.

Todas as operações de contêiner são permitidas em um contêiner que inclui blobs com uma concessão ativa, inclusive Excluir contêiner. Dessa forma, um contêiner poderá ser excluído mesmo se os blobs contidos nele tiverem concessões ativas. Use a operação Contêiner sob concessão para controlar direitos de excluir um contêiner.

As operações de concessão são tratadas pela classe BlobLeaseClient, que fornece um cliente que contém todas as operações de concessão para blobs e contêineres. Para saber mais sobre concessões de contêiner usando a biblioteca de clientes, consulte Criar e gerenciar concessões de contêiner com Python.

Adquirir uma concessão

Ao adquirir uma concessão, você obterá uma ID de concessão que seu código pode usar para operar no blob. Se o blob já tiver uma concessão ativa, você só poderá solicitar uma nova concessão usando a ID de concessão ativa. No entanto, você pode especificar uma nova duração de concessão.

Para adquirir uma concessão, crie uma instância da classe BlobLeaseClient e use um dos métodos a seguir:

Você também pode adquirir uma concessão em um blob criando uma instância de BlobClient e usando o seguinte método:

O exemplo a seguir adquire uma concessão de 30 segundos para um blob:

def acquire_blob_lease(self, blob_service_client: BlobServiceClient, container_name):
    # Instantiate a BlobClient
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Acquire a 30-second lease on the blob
    lease_client = blob_client.acquire_lease(30)

    return lease_client

Renovar uma concessão

Você poderá renovar uma concessão de blob se a ID de concessão especificada na solicitação corresponder à ID de concessão associada ao blob. Observe que a concessão poderá ser renovada mesmo se tiver expirado, desde que o blob não tenha sido alterado nem concedido novamente desde a expiração da concessão. Ao renovar uma concessão, a duração dela é redefinida.

Para renovar uma concessão, use o seguinte método:

O exemplo a seguir renova uma concessão para um blob:

def renew_blob_lease(self, lease_client: BlobLeaseClient):
    # Renew a lease on a blob
    lease_client.renew()

Liberar uma concessão

Você poderá liberar uma concessão de blob se a ID de concessão especificada na solicitação corresponder à ID de concessão associada ao blob. A liberação da concessão permite que outro cliente adquira a concessão do blob assim que a liberação seja concluída.

Você pode liberar uma concessão usando o seguinte método:

O exemplo a seguir libera a concessão em um blob:

def release_blob_lease(self, lease_client: BlobLeaseClient):
    # Release a lease on a blob
    lease_client.release()

Interromper uma concessão

Você poderá interromper uma concessão de blob se o blob tiver uma concessão ativa. Qualquer solicitação autorizada pode interromper a concessão; a solicitação não precisa especificar uma ID de concessão correspondente. Uma concessão não pode ser renovada depois de interrompida, e interromper uma concessão impede que uma nova concessão seja adquirida por um período de tempo até que a concessão original expire ou seja liberada.

Você pode interromper uma concessão usando o seguinte método:

O exemplo a seguir interrompe a concessão em um blob:

def break_blob_lease(self, lease_client: BlobLeaseClient):
    # Break a lease on a blob
    lease_client.break_lease()

Concessão de blobs de forma assíncrona

A biblioteca cliente do Armazenamento de Blobs do Azure para Python é compatível com a concessão de blobs de forma assíncrona. Para saber mais sobre os requisitos de instalação do projeto, confira Programação assíncrona.

Siga estas etapas para concessão de um blob usando APIs assíncronas:

  1. Adicione as seguintes instruções de importação:

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobLeaseClient

  2. Adicione o código para executar o programa usando asyncio.run. Essa função executa a corrotina passada, main() no nosso exemplo, e gerencia o loop de eventos asyncio. As corrotinas são declaradas com a sintaxe async/await. Neste exemplo, a corrotina main() cria primeiro o nível superior BlobServiceClient usando async with e, em seguida, chama o método que adquire a concessão do blob. Observe que somente o cliente de nível superior precisa usar async with, pois os outros clientes criados a partir dele compartilham o mesmo pool de conexões.

    async def main():
    sample = BlobSamples()

    # 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:
        lease_client = await sample.acquire_blob_lease(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Adicione código para adquirir uma concessão de blob. O código é igual ao exemplo síncrono, exceto que o método é declarado com a palavra-chave async e a palavra-chave await é usada ao chamar o método acquire_lease.

    async def acquire_blob_lease(self, blob_service_client: BlobServiceClient, container_name):
    # Instantiate a BlobClient
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Acquire a 30-second lease on the blob
    lease_client = await blob_client.acquire_lease(30)

    return lease_client

Com essa configuração básica em vigor, você pode implementar outros exemplos neste artigo como corrotinas usando sintaxe a async/await.

Estados e ações de concessão

O diagrama a seguir mostra os cinco estados de uma concessão, bem como os comandos ou os eventos que causam alterações no estado da concessão.

A diagram showing blob lease states and state change triggers.

A tabela a seguir lista os cinco estados de concessão, fornece uma breve descrição de cada um e lista as ações de concessão permitidas em um determinado estado. Essas ações de concessão causam transições de estado, conforme mostrado no diagrama.

Estado da concessão Descrição Ações permitidas da concessão
Disponível A concessão está desbloqueada e pode ser adquirida. acquire
Concedida A concessão está bloqueada. acquire (apenas a mesma ID de concessão), renew, change, release e break
Expirada A duração de concessão expirou. acquire, renew, release e break
Quebra A concessão foi interrompida, mas ela permanecerá bloqueada até que o ponto de interrupção expire. release e break
Desfeito A concessão foi interrompida, e o ponto de interrupção expirou. acquire, release, e break

Quando a concessão expira, a ID será mantida pelo serviço Blob até que o blob seja modificado ou sob concessão novamente. Um cliente pode tentar renovar ou liberar a concessão usando a ID de concessão expirada. Se essa operação for bem-sucedida, o cliente saberá que o blob não foi alterado desde que a ID de concessão foi válida pela última vez. Se a solicitação falhar, o cliente sabe que o blob foi modificado ou foi novamente submetido a concessão desde a última vez em que a concessão estava ativa. O cliente deverá adquirir uma nova concessão do blob.

Se uma concessão expirar em vez de ser explicitamente liberada, talvez o cliente precise aguardar um minuto para que seja possível adquirir uma nova concessão para o blob. No entanto, o cliente poderá renovar a concessão com a sua ID imediatamente se o blob não tiver sido modificado.

Uma concessão não pode ser fornecida para um instantâneo de blob, uma vez que instantâneos são somente leitura. A solicitação de uma concessão em um instantâneo resulta no código de status 400 (Bad Request).

Recursos

Para saber mais sobre como gerenciar concessões de blob usando a biblioteca de clientes do Armazenamento de Blobs do Azure para Python, consulte os recursos a seguir.

Operações da API REST

O SDK do Azure para Python contém bibliotecas que se baseiam na API REST do Azure, permitindo a interação com as operações da API REST por meio de paradigmas conhecidos do Python. Os métodos da biblioteca de clientes para gerenciar concessões de blob usam a seguinte operação da API REST:

Exemplos de código

Recursos da biblioteca de clientes

Confira também