Criar e gerenciar concessões de contêiner com o .NET

• .NET
• Java
• JavaScript
• TypeScript
• Python

Este artigo mostra como criar e gerenciar concessões de contêiner usando a biblioteca de clientes do Armazenamento do Azure para .NET. Use a biblioteca de clientes para adquirir, renovar, liberar e interromper concessões de contêiner.

Pré-requisitos

• Assinatura do Azure - criar uma gratuitamente
• Conta de armazenamento do Azure – criar uma conta de armazenamento
• O último SDK do .NET para seu sistema operacional. Obtenha o SDK e não o runtime.

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET. As etapas incluem a instalação do pacote, a adição de diretivas using e a criação de um objeto de cliente autorizado. Para obter detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e ao .NET.

Instalar Pacotes

No diretório do projeto, instale pacotes para as bibliotecas de cliente do Armazenamento de Blobs do Azure e do Azure Identity usando o comando dotnet add package. O pacote Azure.Identity é necessário para conexões sem senha com os serviços do Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Adicione diretivas using

Adicione essas diretivas using ao topo do seu arquivo de código:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Alguns exemplos de código neste artigo podem exigir diretivas using adicionais.

Criar um objeto cliente

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

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Você pode registrar um cliente de serviço para injeção de dependência em um aplicativo .NET.

Você também pode criar objetos cliente para contêineres ou blobs específicos. Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.

Autorização

O mecanismo de autorização deve ter as permissões necessárias para trabalhar com uma concessão de contêiner. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna de Colaborador de Dados de Blob de Armazenamento ou superior do RBAC do Azure. Para saber mais, consulte as diretrizes de autorização para Concessão de Contêiner (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 Criar e gerenciar concessões de blob com .NET.

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:

• Adquirir
• AcquireAsync

O exemplo a seguir adquire uma concessão de 30 segundos para um contêiner:

public static async Task<BlobLeaseClient> AcquireContainerLeaseAsync(
    BlobContainerClient containerClient)
{
    // Get a BlobLeaseClient object to work with a container lease
    BlobLeaseClient leaseClient = containerClient.GetBlobLeaseClient();

    Response<BlobLease> response =
        await leaseClient.AcquireAsync(duration: TimeSpan.FromSeconds(30));

    // Use response.Value to get information about the container lease

    return leaseClient;
}

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 da concessão é redefinida.

Para renovar uma concessão, use um dos seguintes métodos em uma instância de BlobLeaseClient:

• Renovar
• RenewAsync

O exemplo a seguir renova uma concessão de contêiner:

public static async Task RenewContainerLeaseAsync(
    BlobContainerClient containerClient,
    string leaseID)
{
    // Get a BlobLeaseClient object to work with a container lease
    BlobLeaseClient leaseClient = containerClient.GetBlobLeaseClient(leaseID);

    await leaseClient.RenewAsync();
}

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 um dos seguintes métodos em uma instância de BlobLeaseClient:

• Versão
• ReleaseAsync

O exemplo a seguir libera uma concessão em um contêiner:

public static async Task ReleaseContainerLeaseAsync(
    BlobContainerClient containerClient,
    string leaseID)
{
    // Get a BlobLeaseClient object to work with a container lease
    BlobLeaseClient leaseClient = containerClient.GetBlobLeaseClient(leaseID);

    await leaseClient.ReleaseAsync();
}

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 ter sido interrompida. A interrupção de 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 um dos seguintes métodos em uma instância de BlobLeaseClient:

• Break
• BreakAsync

O exemplo a seguir interrompe a concessão em um contêiner:

public static async Task BreakContainerLeaseAsync(
    BlobContainerClient containerClient)
{
    // Get a BlobLeaseClient object to work with a container lease
    BlobLeaseClient leaseClient = containerClient.GetBlobLeaseClient();

    await leaseClient.BreakAsync();
}

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 gerenciar concessões de contêiner usando a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET, confira os recursos a seguir.

Exemplos de código

• Exibir exemplos de código deste artigo (GitHub)

Operações da API REST

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

• Lease Container

Recursos da biblioteca de clientes

• Documentação de referência da biblioteca de clientes
• Código-fonte da biblioteca de clientes
• Pacote (NuGet)

Confira também

• Gerenciando Simultaneidade em Armazenamento de Blobs

Conteúdo relacionado

• Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para .NET. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo .NET.