Condividi tramite

Copiare un BLOB con pianificazione asincrona tramite Java

  • Articolo

Questo articolo illustra come copiare un BLOB con pianificazione asincrona usando la libreria client di Archiviazione di Azure per Java. È possibile copiare un BLOB da un'origine all'interno dello stesso account di archiviazione, da un'origine in un account di archiviazione diverso o da qualsiasi oggetto accessibile recuperato tramite una richiesta HTTP GET in un determinato URL. È anche possibile interrompere un'operazione di copia in sospeso.

I metodi della libreria client illustrati in questo articolo usano l'operazione API REST Copy BLOB e possono essere usati quando si vuole eseguire una copia con pianificazione asincrona. Per la maggior parte degli scenari di copia in cui si vogliono spostare i dati in un account di archiviazione e si ha un URL per l'oggetto di origine, vedere Copiare un BLOB da un URL dell'oggetto di origine con Java.

Prerequisiti

  • Questo articolo presuppone che sia già stato configurato un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per Java. Per informazioni sulla configurazione del progetto, incluse l'installazione del pacchetto, l'aggiunta di direttive import e la creazione di un oggetto client autorizzato, vedere Introduzione ad Archiviazione di Azure e Java.
  • Il meccanismo di autorizzazione deve disporre delle autorizzazioni per eseguire un'operazione di copia o per interrompere una copia in sospeso. Per altre informazioni, vedere le linee guida per l'autorizzazione per le operazioni API REST seguenti:

Informazioni sulla copia di BLOB con pianificazione asincrona

L'operazione Copy Blob può terminare in modo asincrono e viene eseguita secondo il criterio del massimo sforzo, il che significa che non sono garantiti l'avvio immediato dell'operazione o il completamento entro un intervallo di tempo specificato. L'operazione di copia viene pianificata in background ed eseguita non appena il server ha risorse disponibili. L'operazione può essere completata in modo sincrono se la copia avviene all'interno dello stesso account di archiviazione.

Un'operazione Copy Blob può eseguire una delle azioni seguenti:

  • Copiare un BLOB di origine in un BLOB di destinazione con un nome diverso. Il BLOB di destinazione può essere un BLOB esistente dello stesso tipo (BLOB in blocchi, di accodamento o di pagine) oppure può trattarsi di un nuovo BLOB creato dall'operazione di copia.
  • Copiare un BLOB di origine in un BLOB di destinazione con lo stesso nome, sostituendo così il BLOB di destinazione. Questo tipo di operazione di copia rimuove i blocchi non sottoposti a commit e sovrascrive i metadati del BLOB di destinazione.
  • Copiare un file di origine nel servizio file di Azure in un BLOB di destinazione. Il BLOB di destinazione può essere un BLOB in blocchi esistente o può trattarsi di un nuovo BLOB in blocchi creato dall'operazione di copia. La copia da file a BLOB di pagine o BLOB di accodamento non è supportata.
  • Copiare uno snapshot sul relativo BLOB di base. Promuovendo uno snapshot alla posizione del BLOB di base, è possibile ripristinare la versione precedente di un BLOB.
  • Copiare uno snapshot in un BLOB di destinazione con un nome diverso. Il BLOB di destinazione risultante è un BLOB scrivibile, non uno snapshot.

Per altre informazioni sull'operazione Copy Blob, incluse le informazioni sulle proprietà, i tag di indice, i metadati e la fatturazione, vedere le osservazioni sull'operazione Copy Blob.

Copiare un BLOB con pianificazione asincrona

Questa sezione offre una panoramica dei metodi forniti dalla libreria client di Archiviazione di Azure per Java per eseguire un'operazione di copia con pianificazione asincrona.

Il metodo seguente esegue il wrapping dell'operazione API REST Copy BLOB e avvia una copia asincrona dei dati dal BLOB di origine:

Il metodo beginCopy restituisce un oggetto SyncPoller per eseguire il polling dello stato di avanzamento dell'operazione di copia. Il tipo di risposta di polling è BlobCopyInfo. Il metodo beginCopy viene usato quando si vuole pianificare in modo asincrono un'operazione di copia.

Copiare un BLOB da un'origine all'interno di Azure

Se si copia un BLOB all'interno dello stesso account di archiviazione, l'operazione può essere completata in modo sincrono. L'accesso al BLOB di origine può essere autorizzato tramite Microsoft Entra ID, una firma di accesso condiviso o una chiave dell'account. Per un'operazione di copia sincrona alternativa, vedere Copiare un BLOB da un URL dell'oggetto di origine con Java.

Se l'origine della copia è un BLOB in un account di archiviazione diverso, l'operazione può essere completata in modo asincrono. Il BLOB di origine deve essere pubblico o autorizzato tramite token di firma di accesso condiviso. Il token di firma di accesso condiviso deve includere l'autorizzazione di lettura ('r'). Per altre informazioni sui token di firma di accesso condiviso, vedere Delegare l'accesso con firme di accesso condiviso.

L'esempio seguente illustra uno scenario per la copia di un BLOB di origine da un account di archiviazione diverso con pianificazione asincrona. In questo esempio viene creato un URL del BLOB di origine con un token di firma di accesso condiviso di delega utente aggiunto. L'esempio mostra come generare il token di firma di accesso condiviso usando la libreria client, ma è anche possibile specificare il proprio. L'esempio mostra anche come creare un lease sul BLOB di origine durante l'operazione di copia per impedire modifiche al BLOB da un client diverso. L'operazione Copy Blob salva il valore ETag del BLOB di origine all'avvio dell'operazione di copia. Se il valore ETag viene modificato prima del completamento dell'operazione di copia, l'operazione non riesce.

public void copyBlobAcrossStorageAccounts(BlobClient sourceBlob, BlockBlobClient destinationBlob) {
    // Lease the source blob during copy to prevent other clients from modifying it
    BlobLeaseClient lease = new BlobLeaseClientBuilder()
            .blobClient(sourceBlob)
            .buildClient();

    // Create a SAS token for the source blob or use an existing one
    String sasToken = generateUserDelegationSAS(
            sourceBlob.getContainerClient().getServiceClient(),
            sourceBlob);

    // Get the source blob URL and append the SAS token
    String sourceBlobSasURL = sourceBlob.getBlobUrl() + "?" + sasToken;

    try {
        // Specifying -1 creates an infinite lease
        lease.acquireLease(-1);

        // Start the copy operation and wait for it to complete
        final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
                sourceBlobSasURL,
                Duration.ofSeconds(2));
        PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
    } finally {
        // Release the lease once the copy operation completes
        lease.releaseLease();
    }
}

public String generateUserDelegationSAS(BlobServiceClient blobServiceClient, BlobClient sourceBlob) {
    // Get a user delegation key
    OffsetDateTime delegationKeyStartTime = OffsetDateTime.now();
    OffsetDateTime delegationKeyExpiryTime = OffsetDateTime.now().plusDays(1);
    UserDelegationKey key = blobServiceClient.getUserDelegationKey(
        delegationKeyStartTime,
        delegationKeyExpiryTime);

    // Create a SAS token that's valid for one day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Set the Read (r) permission on the SAS token
    BlobSasPermission permission = new BlobSasPermission().setReadPermission(true);

    BlobServiceSasSignatureValues sasValues = new BlobServiceSasSignatureValues(expiryTime, permission)
            .setStartTime(OffsetDateTime.now());

    // Create a SAS token that's valid for one day
    String sasToken = sourceBlob.generateUserDelegationSas(sasValues, key);

    return sasToken;
}

Nota

I token di firma di accesso condiviso di delega utente offrono maggiore sicurezza, perché sono firmati con le credenziali di Microsoft Entra anziché con una chiave dell'account. Per creare un token di firma di accesso condiviso di delega utente, l'entità di sicurezza di Microsoft Entra necessita delle autorizzazioni appropriate. Per i requisiti di autorizzazione, vedere Get User Delegation Key.

Copiare un BLOB da un'origine all'esterno di Azure

È possibile eseguire un'operazione di copia su qualsiasi oggetto di origine recuperabile tramite una richiesta HTTP GET in un determinato URL, inclusi gli oggetti accessibili all'esterno di Azure. L'esempio seguente illustra uno scenario per la copia di un BLOB da un URL dell'oggetto di origine accessibile.

public void copyFromExternalSourceAsyncScheduling(String sourceURL, BlockBlobClient destinationBlob) {
    // Start the copy operation and wait for it to complete
    final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
            sourceURL,
            Duration.ofSeconds(2));
    PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
}

Controllare lo stato di un'operazione di copia

Per controllare lo stato di un'operazione Copy Blob, è possibile chiamare getCopyStatus nell'oggetto BlobCopyInfo restituito da SyncPoller.

L'esempio di codice seguente illustra come controllare lo stato di un'operazione di copia:

public void checkCopyStatus(BlobCopyInfo copyInfo) {
    // Check the status of the copy operation 
    System.out.printf("Copy status", copyInfo.getCopyStatus());
}

Interrompere un'operazione di copia

L'interruzione di un'operazione Copy Blob in sospeso produce un BLOB di destinazione di lunghezza zero. Per i metadati del BLOB di destinazione, tuttavia, i nuovi valori verranno copiati dal BLOB di origine o impostati in modo esplicito durante l'operazione di copia. Per mantenere i metadati originali risalenti a prima della copia, creare uno snapshot del BLOB di destinazione prima di chiamare uno dei metodi di copia.

Per interrompere un'operazione di copia in sospeso, chiamare il metodo seguente:

Questo metodo esegue il wrapping dell'operazione API REST Abort Copy Blob, che annulla un'operazione Copy Blob in sospeso. L'esempio di codice seguente illustra come interrompere un'operazione Copy Blob in sospeso:

public void abortCopy(BlobCopyInfo copyInfo, BlobClient destinationBlob) {
    // Check the copy status and abort if pending
    if (copyInfo.getCopyStatus() == CopyStatusType.PENDING) {
        destinationBlob.abortCopyFromUrl(copyInfo.getCopyId());
        System.out.printf("Copy operation %s has been aborted%n", copyInfo.getCopyId());
    }
}

Risorse

Per altre informazioni sulla copia di BLOB con la libreria client di Archiviazione BLOB di Azure per Java, vedere le risorse seguenti.

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 illustrati in questo articolo usano le operazioni API REST seguenti:

Esempi di codice

Risorse della libreria client