Criar e gerenciar concessões de contêiner com o Python
Esse artigo mostra como criar e gerenciar concessões de contêiner usando a biblioteca de clientes do Armazenamento do Microsoft Azure para Python. Use a biblioteca de clientes para adquirir, renovar, liberar e interromper concessões de contêiner.
Para saber mais sobre a concessão de um contêiner de blobs usando APIs assíncronas, consulte Concessão de contêineres 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 o tempo de concessão de blob. Para saber mais, consulte as diretrizes de autorização para as seguintes operações de API REST:
Sobre as concessões de contêiner
Uma concessão estabelece e gerencia um bloqueio em um contêiner para operações de exclusão. A duração do bloqueio pode ser de 15 a 60 segundos, ou pode ser infinita. Uma concessão em um contêiner fornece acesso de gravação e exclusão exclusivo ao contêiner. A concessão do contêiner controla somente a capacidade de excluir o contêiner usando a operação Excluir Contêiner da API REST. Para excluir um contêiner com uma concessão ativa, o cliente deve incluir a ID da concessão ativa com a solicitação de exclusão. Todas as outras operações de contêiner são realizadas com êxito em um contêiner concedido sem a ID da concessão. Se você habilitou a exclusão temporária de contêiner, é possível restaurar contêineres excluídos.
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.
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 blob usando a biblioteca de clientes, confira Como criar e gerenciar concessões de blob com Python.
Adquirir uma concessão
Ao adquirir uma concessão de contêiner, você obterá uma ID de concessão que o código poderá usar para operar no contêiner. Se o contêiner 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 usando o seguinte método da classe ContainerClient:
O exemplo a seguir adquire uma concessão de 30 segundos em um contêiner:
def acquire_container_lease(self, blob_service_client: BlobServiceClient, container_name):
# Instantiate a ContainerClient
container_client = blob_service_client.get_container_client(container=container_name)
# Acquire a 30-second lease on the container
lease_client = container_client.acquire_lease(30)
return lease_client
Renovar uma concessão
Você pode renovar uma concessão de contêiner se a ID de concessão especificada na solicitação corresponder à ID de concessão associada ao contêiner. A concessão pode ser renovada mesmo se tiver expirada, desde que o contêiner não tenha sido 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 contêiner:
def renew_container_lease(self, lease_client: BlobLeaseClient):
# Renew a lease on the container
lease_client.renew()
Liberar uma concessão
Você poderá liberar uma concessão de contêiner se a ID de concessão especificada na solicitação corresponder à ID de concessão associada ao contêiner. A liberação da concessão permite que outro cliente adquira a concessão do contêiner imediatamente assim que a liberação é concluída.
Você pode liberar uma concessão usando o seguinte método:
O exemplo a seguir libera a concessão em um contêiner:
def release_container_lease(self, lease_client: BlobLeaseClient):
# Release a lease on the container
lease_client.release()
Interromper uma concessão
Você pode interromper uma concessão de contêiner se o contêiner 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 contêiner:
def break_container_lease(self, lease_client: BlobLeaseClient):
# Break a lease on the container
lease_client.break_lease()
Concessão de contêineres de forma assíncrona
A biblioteca de clientes do Armazenamento de Blobs do Azure para Python dá suporte para a concessão de contêineres de forma assíncrona. Para saber mais sobre os requisitos de instalação do projeto, confira Programação assíncrona.
Siga estas etapas para fazer a concessão de um contêiner utilizando APIs assíncronas:
Adicione as seguintes instruções de importação:
import asyncio from azure.identity.aio import DefaultAzureCredential from azure.storage.blob.aio import BlobServiceClient, BlobLeaseClient
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 eventosasyncio
. As corrotinas são declaradas com a sintaxe async/await. Neste exemplo, a corrotinamain()
cria primeiro o nível superiorBlobServiceClient
usandoasync with
e, em seguida, chama o método que adquire a concessão do contêiner. Observe que somente o cliente de nível superior precisa usarasync with
, pois os outros clientes criados a partir dele compartilham o mesmo pool de conexões.async def main(): sample = ContainerSamples() # 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_container_lease(blob_service_client, "sample-container") if __name__ == '__main__': asyncio.run(main())
Adicione código para adquirir uma concessão de contêiner. O código é igual ao exemplo síncrono, exceto que o método é declarado com a palavra-chave
async
e a palavra-chaveawait
é usada ao chamar o métodoacquire
.async def acquire_container_lease(self, blob_service_client: BlobServiceClient, container_name): # Instantiate a ContainerClient container_client = blob_service_client.get_container_client(container=container_name) # Acquire a 30-second lease on the container lease_client = BlobLeaseClient(container_client) await lease_client.acquire(lease_duration=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 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 contêiner 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 a solicitação falhar, o cliente sabe que o contêiner foi novamente submetido a concessão ou foi excluído desde a última vez em que a concessão estava ativa.
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 contêiner. No entanto, o cliente pode renovar a concessão com a ID expirada imediatamente.
Recursos
Para saber mais sobre como obter a concessão de um contêiner 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 obter uma concessão de um contêiner usam a seguinte operação de API REST:
- Obter concessão de contêiner (API REST)
Exemplos de código
- Exibir exemplos de código síncrono ou assíncrono deste artigo (GitHub)
Recursos da biblioteca de clientes
- Documentação de referência da biblioteca de clientes
- Código-fonte da biblioteca de clientes
- Pacote (PyPi)