Criar e gerenciar concessões de blob com o Java
Esse artigo mostra como criar e gerenciar concessões de blob usando a biblioteca de clientes do Armazenamento do Microsoft Azure para Java. Você pode usar a biblioteca de clientes para adquirir, renovar, liberar e interromper concessões de blob.
Pré-requisitos
- Assinatura do Azure - criar uma gratuitamente
- Conta de armazenamento do Azure – criar uma conta de armazenamento
- JDK (Java Development Kit) versão 8 ou posterior (recomendamos a versão 17 para ter a melhor experiência)
- O Apache Maven é usado para o gerenciamento de projetos neste exemplo
Configure seu ambiente
Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para que ele funcione com a biblioteca de clientes do Armazenamento de Blobs do Azure para Java. Para obter mais informações, confira Introdução ao Armazenamento de Blobs do Azure e ao Java.
Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.
Observação
Este artigo usa a ferramenta de build do Maven para compilar e executar o código de exemplo. Outras ferramentas de build, como o Gradle, também funcionam com o SDK do Azure para Java.
Instalar Pacotes
Abra o arquivo pom.xml no seu editor de texto. Instale os pacotes incluindo o arquivo BOM ou incluindo uma dependência direta.
Adicionar instruções de importação
Adicione as seguintes declarações de import :
import com.azure.storage.blob.*;
import com.azure.storage.blob.specialized.*;
Autorização
O mecanismo de autorização deve ter as permissões necessárias para trabalhar com uma concessão de blob. 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 Blob (API REST).
Criar um objeto cliente
Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância do BlobServiceClient.
O exemplo a seguir usa BlobServiceClientBuilder para criar um objeto BlobServiceClient usando DefaultAzureCredential e mostra como criar clientes de contêiner e blob, se necessário:
// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
.endpoint("https://<storage-account-name>.blob.core.windows.net/")
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
.getBlobContainerClient("<container-name>");
// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
.getBlobClient("<blob-name>");
Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.
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 Java.
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:
O exemplo a seguir adquire uma concessão de 30 segundos para um blob:
public BlobLeaseClient acquireBlobLease(BlobClient blob) {
// Create the lease client
BlobLeaseClient leaseClient = new BlobLeaseClientBuilder()
.blobClient(blob)
.buildClient();
// Acquire the lease - specify duration between 15 and 60 seconds, or -1 for
// infinite duration
String leaseID = leaseClient.acquireLease(30);
System.out.printf("Acquired lease ID: %s%n", leaseID);
return leaseClient;
}
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 existente, use o seguinte método:
O exemplo a seguir renova uma concessão para um blob:
public void renewBlobLease(BlobLeaseClient leaseClient) {
leaseClient.renewLease();
}
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:
public void releaseBlobLease(BlobLeaseClient leaseClient) {
leaseClient.releaseLease();
System.out.println("Release lease operation completed");
}
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:
public void breakBlobLease(BlobLeaseClient leaseClient) {
leaseClient.breakLease();
}
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 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 Java, consulte os recursos a seguir:
Exemplos de código
Operações da API REST
O SDK do Azure para Java 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 Java. Os métodos da biblioteca de clientes para gerenciar concessões de blob usam a seguinte operação da API REST:
Recursos da biblioteca de clientes
- Documentação de referência da biblioteca de clientes
- Código-fonte da biblioteca de clientes
- Pacote (Maven)
Confira também
Conteúdo relacionado
- Este artigo faz parte do guia do desenvolvedor do Armazenamento de Blobs para Java. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Java.