Creare e gestire lease di contenitori con Java

  • Articolo

Questo articolo illustra come creare e gestire i lease di contenitori usando la libreria client di Archiviazione di Azure per Java. È possibile usare la libreria client per acquisire, rinnovare, rilasciare e interrompere i lease dei contenitori.

Prerequisiti

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione illustra come configurare un progetto per l’uso con la libreria client di Archiviazione BLOB di Azure per Java. Per altre informazioni, vedere Introduzione all’Archiviazione BLOB di Azure e Java.

Per usare gli esempi di codice in questo articolo, seguire questa procedura per configurare il progetto.

Nota

Questo articolo usa lo strumento di compilazione Maven per compilare ed eseguire il codice di esempio. Anche altri strumenti di compilazione, come Gradle, sono compatibili con Azure SDK per Java.

Installare i pacchetti

Aprire il file pom.xml nell'editor di testo. Installare i pacchetti includendo il file BOM o includendo una dipendenza diretta.

Aggiungere le istruzioni di importazione

Aggiungere le istruzioni import seguenti:

import com.azure.storage.blob.*;
import com.azure.storage.blob.specialized.*;

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per lavorare con un lease del contenitore. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), è necessario disporre del ruolo predefinito di Controllo degli accessi in base al ruolo di Azure Collaboratore ai dati del BLOB di archiviazione o ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Contenitore di lease (API REST).

Creare un oggetto client

Per connettere un'app ad Archiviazione BLOB, creare un'istanza di BlobServiceClient.

L’esempio seguente usa BlobServiceClientBuilder per compilare un oggetto BlobServiceClient usando DefaultAzureCredential e illustra come creare client blob e contenitori, se necessario:

// 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>");

Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

Informazioni sui lease di contenitori

Un lease stabilisce e gestisce un blocco su un contenitore per le operazioni di eliminazione. La durata del blocco può variare da 15 a 60 secondi o può essere infinita. Un lease su un contenitore fornisce un accesso esclusivo con diritti di eliminazione al contenitore. Il lease del contenitore controlla unicamente la possibilità di eliminare il contenitore tramite l'operazione API REST Delete Container. Per eliminare un contenitore con un lease attivo, un client deve includere l'ID lease attivo con la richiesta di eliminazione. Tutte le altre operazioni hanno esito positivo su un contenitore con lease senza ID del lease. Se è stata abilitata l'eliminazione temporanea dei contenitori, sarà possibile ripristinare i contenitori eliminati.

Per ulteriori informazioni sugli stati dei lease e sapere quando è possibile eseguire una determinata azione su un lease, consultare Stati e azioni dei lease.

Le operazioni di lease vengono gestite dalla classe BlobLeaseClient, che fornisce un client contenente tutte le operazioni di lease per BLOB e contenitori. Per altre informazioni sui lease di BLOB tramite la libreria client, vedere Creare e gestire lease di BLOB con Java.

Acquisire un lease

Quando si acquisisce un lease di contenitore, si ottiene un ID del lease che può essere utilizzato dal codice per operare sul contenitore. Se il contenitore ha già un lease attivo, si può fare una richiesta per un nuovo lease soltanto utilizzando l'ID del lease attivo. Tuttavia, è possibile specificare una nuova durata del lease.

Per acquisire un lease, creare un'istanza della classe BlobLeaseClient e quindi usare il metodo seguente:

Il seguente esempio acquisisce un lease di 30 secondi per un contenitore:

public BlobLeaseClient acquireContainerLease(BlobContainerClient container) {
    // Create the lease client
    BlobLeaseClient leaseClient = new BlobLeaseClientBuilder()
            .containerClient(container)
            .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;
}

Rinnovare un lease

È possibile rinnovare un lease di contenitore se l'ID del lease specificato nella richiesta corrisponde all'ID del lease associato al contenitore. Il lease può essere rinnovato anche se scaduto, purché il contenitore non sia stato associato a un nuovo lease dopo la scadenza di quello corrente. Quando si rinnova un lease, la durata del lease viene reimpostata.

Per rinnovare un lease esistente, usare il metodo seguente:

L'esempio seguente rinnova un lease per un contenitore:

public void renewContainerLease(BlobLeaseClient leaseClient) {
    leaseClient.renewLease();
}

Rilasciare un lease

È possibile rilasciare un lease di contenitore se l'ID del lease specificato nella richiesta corrisponde all'ID del lease associato al contenitore. Quando si rilascia un lease si consente a un altro client di acquisire un lease per il contenitore subito dopo il completamento del rilascio.

È possibile rilasciare un lease usando il metodo seguente:

L'esempio seguente rilascia il lease in un contenitore:

public void releaseContainerLease(BlobLeaseClient leaseClient) {
    leaseClient.releaseLease();
    System.out.println("Release lease operation completed");
}

Interrompere un lease

È possibile interrompere un lease di un contenitore se il contenitore ha un lease attivo. Qualsiasi richiesta autorizzata può interrompere il lease. Non è necessario che nella richiesta sia specificato un ID del lease corrispondente. Un lease non può essere rinnovato dopo che è stato interrotto e l'interruzione di un lease impedisce di acquisirne uno nuovo per un certo periodo, ossia fino alla scadenza o al rilascio del lease originale.

È possibile interrompere un lease usando il metodo seguente:

L'esempio seguente interrompe il lease in un contenitore:

public void breakContainerLease(BlobLeaseClient leaseClient) {
    leaseClient.breakLease();
}

Stati e azioni dei lease

Il diagramma seguente illustra i cinque stati di un lease e i comandi o gli eventi che causano modifiche dello stato del lease.

Diagramma che mostra gli stati dei lease del contenitore e i trigger di modifica dello stato.

La tabella seguente elenca i cinque stati di lease, fornisce una breve descrizione di ognuno di essi ed elenca le azioni di lease consentite in un determinato stato. Queste azioni di lease causano transizioni di stato, come illustrato nel diagramma.

Stato lease Descrizione Azioni di lease consentite
Disponibile Il lease è sbloccato e può essere acquisito. acquire
Sottoposto a lease Il lease è bloccato. acquire (solo stesso ID del lease), renew, change, release e break
Scaduta La durata del lease è scaduta. acquire, renew, release e break
Interruzione Il lease è stato interrotto, ma rimarrà bloccato fino alla scadenza del periodo di interruzione. release e break
Interrotto Il lease è stato interrotto e il periodo di interruzione è scaduto. acquire, release e break

Quando un lease scade, il relativo ID viene mantenuto dal servizio BLOB finché il contenitore non viene modificato o gli viene associato un nuovo lease. Un client può provare a rinnovare o rilasciare il lease utilizzando l'ID del lease scaduto. Se la richiesta ha esito negativo, il client sa che il contenitore è stato associato a un nuovo lease o è stato eliminato dall'ultima volta che il lease era attivo.

Se un lease scade anziché essere rilasciato in modo esplicito, è possibile che il client debba attendere fino a un minuto prima di poter acquisire un nuovo lease per il contenitore. Tuttavia, il client può rinnovare immediatamente il lease con l'ID del lease scaduto.

Risorse

Per altre informazioni sul lease dei contenitori tramite la libreria client di Archiviazione BLOB di Azure per Java, vedere le risorse seguenti.

Esempi di codice

Operazioni dell'API REST

Azure SDK per Java contiene librerie basate sull'API REST di Azure, che consentono di interagire con le operazioni dell'API REST tramite paradigmi Java noti. I metodi della libreria client per il lease dei contenitori usano l'operazione API REST seguente:

Risorse della libreria client

Vedi anche

Contenuto correlato

  • Questo articolo fa parte della guida per sviluppatori di Archiviazione BLOB per Java. Per altre informazioni, vedere l'elenco completo degli articoli della Guida per sviluppatori in Creare la propria app Java.