Partilhar via

Crie e gerencie concessões de blob com Python

  • Artigo

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

Para saber mais sobre como alugar um blob usando APIs assíncronas, consulte Conceder blobs de forma assíncrona.

Pré-requisitos

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

Sobre locaçõ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 exclusivo de gravação e exclusão ao blob. Para gravar em um blob com uma concessão ativa, um cliente deve incluir o ID de concessão ativo com a solicitação de gravação.

Para saber mais sobre estados de concessão e quando você pode executar uma determinada ação em uma concessão, consulte 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, incluindo Excluir Contêiner. Portanto, um contêiner pode ser excluído mesmo se os blobs dentro dele tiverem concessões ativas. Use a operação Lease Container para controlar os direitos de exclusão de um contêiner.

As operações de leasing são tratadas pela classe BlobLeaseClient , que fornece um cliente contendo 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 cliente, consulte Criar e gerenciar concessões de contêiner com Python.

Adquira um contrato de arrendamento

Ao adquirir uma concessão de blob, você obtém 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 o ID de concessão ativo. 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 o seguinte método:

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 um contrato de arrendamento

Você pode renovar uma concessão de blob se a ID de concessão especificada na solicitação corresponder à ID de concessão associada ao blob. O contrato de arrendamento pode ser renovado mesmo que tenha expirado, desde que o blob não tenha sido modificado ou arrendado novamente desde a expiração desse contrato. Quando você renova uma locação, a duração da locação é 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 um contrato de arrendamento

Você pode 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 de uma locação permite que outro cliente adquira uma locação para o blob imediatamente após a conclusão da liberação.

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

Quebrar um contrato de arrendamento

Você pode quebrar uma concessão de blob se o blob tiver uma concessão ativa. Qualquer pedido autorizado pode quebrar o contrato de arrendamento; a solicitação não é necessária para especificar um ID de concessão correspondente. Um contrato de arrendamento não pode ser renovado depois de quebrado, e quebrar um contrato impede que um novo contrato seja adquirido por um período de tempo até que o contrato original expire ou seja liberado.

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

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

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

Conceder blobs de forma assíncrona

A biblioteca de cliente do Armazenamento de Blobs do Azure para Python dá suporte à locação de blobs de forma assíncrona. Para saber mais sobre os requisitos de configuração do projeto, consulte Programação assíncrona.

Siga estas etapas para conceder 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 código para executar o programa usando asyncio.runo . Essa função executa a co-rotina passada, em nosso exemplo, main() e gerencia o loop de asyncio eventos. As co-rotinas são declaradas com a sintaxe async/await. Neste exemplo, a co-rotina primeiro cria o nível BlobServiceClient superior usando async withe, em seguida, chama o método que adquire a main() concessão de blob. Observe que apenas o cliente de nível superior precisa usar async witho , pois 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 é o mesmo que o exemplo síncrono, exceto que o método é declarado com a palavra-chave e a asyncawait palavra-chave é usada ao chamar o acquire_lease método.

    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 co-rotinas usando a sintaxe async/await.

Estados e ações de arrendamento

O diagrama a seguir mostra os cinco estados de uma concessão e os comandos ou 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 de arrendamento Description Ações de arrendamento permitidas
Disponível O contrato de arrendamento é desbloqueado e pode ser adquirido. acquire
Arrendado A locação está bloqueada. acquire(apenas o mesmo ID de concessão), renew, , , changereleaseebreak
Expirada A duração da locação expirou. acquire, , , renewreleaseebreak
Quebrando O contrato de arrendamento foi quebrado, mas o contrato continuará bloqueado até que o período de interrupção tenha expirado. release e break
Quebrado O contrato de arrendamento foi quebrado e o período de interrupção expirou. acquire, , releasee break

Quando uma concessão expira, a ID da concessão é mantida pelo serviço de Blob até que o blob seja modificado ou alugado novamente. Um cliente pode tentar renovar ou liberar a concessão usando o ID de concessão expirado. Se essa operação for bem-sucedida, o cliente saberá que o blob não foi alterado desde que o ID de concessão foi válido pela última vez. Se a solicitação falhar, o cliente sabe que o blob foi modificado ou que o blob foi alugado novamente desde que a concessão foi ativada pela última vez. O cliente deve então adquirir uma nova locação no blob.

Se uma concessão expirar em vez de ser explicitamente liberada, um cliente pode precisar esperar até um minuto antes que uma nova concessão possa ser adquirida para o blob. No entanto, o cliente pode renovar a concessão com seu ID de concessão imediatamente se o blob não tiver sido modificado.

Uma concessão não pode ser concedida para um instantâneo de blob, pois os instantâneos são somente leitura. Solicitar uma concessão em relação a um instantâneo resulta em código 400 (Bad Request)de status .

Recursos

Para saber mais sobre como gerenciar concessões de blob usando a biblioteca de cliente 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 que você interaja com operações da API REST por meio de paradigmas Python familiares. Os métodos de biblioteca de cliente para gerenciar concessões de blob usam a seguinte operação de API REST:

Amostras de código

Recursos da biblioteca do cliente

Consulte também