Partilhar via

Crie e gerencie concessões de contêiner com Python

  • Artigo

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

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

Pré-requisitos

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Python. Para obter mais detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e Python.

Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.

Instalar pacotes

Instale os seguintes pacotes usando pip install:

pip install azure-storage-blob azure-identity

Adicionar instruções de importação

Adicione as seguintes instruções import:

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

Autorização

O mecanismo de autorização deve ter as permissões necessárias para trabalhar com uma locação de contêiner. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna do RBAC do Azure RBAC Storage Blob Data Contributor ou superior. Para saber mais, consulte as diretrizes de autorização para Lease Container (REST API).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância de BlobServiceClient. O exemplo a seguir mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

Você também pode criar objetos de cliente para contêineres ou blobs específicos, diretamente ou a partir do BlobServiceClient objeto. Para saber mais sobre como criar e gerenciar objetos de cliente, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Sobre locações de contêineres

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 locação em um contêiner fornece acesso exclusivo de exclusão ao contêiner. Uma concessão de contêiner controla apenas a capacidade de excluir o contêiner usando a operação Excluir API REST de contêiner . Para excluir um contêiner com uma concessão ativa, um cliente deve incluir a ID de concessão ativa com a solicitação de exclusão. Todas as outras operações de contêiner são bem-sucedidas em um contêiner alugado sem o ID de locação. Se você tiver habilitado a exclusão suave de contêiner, poderá restaurar contêineres excluídos.

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.

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 blob usando a biblioteca de cliente, consulte Criar e gerenciar concessões de blob com Python.

Adquira um contrato de arrendamento

Ao adquirir uma concessão de contêiner, você obtém uma ID de concessão que seu código pode 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 o seguinte método:

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

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. O contrato de arrendamento pode ser renovado mesmo que tenha expirado, desde que o contentor não tenha sido alugado novamente desde o termo desse contrato. Quando você renova uma locação, a duração da concessão é 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 um contrato de arrendamento

Você pode 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 de uma locação permite que outro cliente adquira uma locação para o contêiner 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 contêiner:

def release_container_lease(self, lease_client: BlobLeaseClient):
    # Release a lease on the container
    lease_client.release()

Quebrar um contrato de arrendamento

Você pode interromper uma concessão de contêiner se o contêiner 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 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()

Alugar contêineres de forma assíncrona

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

Siga estas etapas para alugar um contêiner 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, main() em nosso exemplo, e gerencia o loop de asyncio eventos. As co-rotinas são declaradas com a sintaxe async/await. Neste exemplo, a main() co-rotina primeiro cria o nível BlobServiceClient superior usando async withe, em seguida, chama o método que adquire a concessão de contêiner. 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 = 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())

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

    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 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 de estado de concessão.

Um diagrama mostrando estados de concessão de contêiner e gatilhos de alteração de estado.

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 está desbloqueado e pode ser adquirido. acquire
Arrendado A locação está bloqueada. acquire (apenas o mesmo ID de concessão), renew, change, release, e break
Expirada A duração da locação expirou. acquire, renew, release, e break
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, release, e break

Quando uma concessão expira, a ID da concessão é mantida pelo serviço de Blob até que o contêiner seja modificado ou alugado novamente. Um cliente pode tentar renovar ou liberar a concessão usando o ID de concessão expirado. Se a solicitação falhar, o cliente saberá que o contêiner foi alugado novamente ou que o contêiner foi excluído desde que a concessão foi ativada pela última vez.

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 contêiner. No entanto, o cliente pode renovar a concessão com o ID de concessão expirado imediatamente.

Recursos

Para saber mais sobre como alugar um contêiner usando a biblioteca de cliente do Armazenamento de Blobs do Azure para Python, consulte os recursos a seguir.

Amostras de código

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 alugar um contêiner usam a seguinte operação de API REST:

Recursos da biblioteca do cliente

Consulte também

Conteúdos relacionados

  • Este artigo faz parte do guia do desenvolvedor do Blob Storage para Python. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Build your Python app.