Gestione delle operazioni a lunga esecuzione

Un'operazione a lunga esecuzione (LRO) è un metodo API il cui completamento richiede più tempo di quanto sia appropriato per una risposta API. In genere, non è consigliabile mantenere aperto il thread di chiamata durante l'esecuzione dell'attività, in quanto offre un'esperienza utente negativa. È meglio restituire all'utente un qualche tipo di promessa e consentirgli di tornare più tardi.

L'API Google Drive restituisce un LRO ogni volta che chiami il metodo download() nella risorsa files per scaricare i contenuti di un file tramite l'API Drive o le relative librerie client.

Il metodo restituisce al client una risorsa operations. Puoi utilizzare la risorsa operations per recuperare in modo asincrono lo stato del metodo dell'API eseguendo il polling dell'operazione tramite il metodo get(). Le entità LRO nell'API Drive rispettano il pattern di progettazione delle entità LRO di Google Cloud.

Per ulteriori informazioni, consulta Operazioni di lunga durata.

Panoramica sulla procedura

Il seguente diagramma mostra i passaggi di alto livello del funzionamento del metodo file.download.

1. Chiama files.download: quando l'app chiama il metodo download(), avvia la richiesta di download dell'API Drive per il file. Per ulteriori informazioni, vedi Scaricare file.

2. Richiedi autorizzazioni: la richiesta invia le credenziali di autenticazione all'API Drive. Se la tua app richiede di chiamare l'API Drive utilizzando l'autenticazione di un utente che non è stata ancora concessa, chiede all'utente di accedere. La tua app richiede anche l'accesso con ambiti specificati durante la configurazione dell'autenticazione.

3. Avvia download: viene inviata una richiesta all'API Drive per avviare il download del file. La richiesta può essere presentata a Google Vids o ad altri contenuti di Google Workspace.

4. Avvia LRO: viene avviata un'operazione a lunga esecuzione che gestisce il processo di download.

5. Restituisce un'operazione in attesa: l'API Drive restituisce un'operazione in attesa contenente informazioni sull'utente che effettua la richiesta e diversi campi dei metadati dei file.

6. Stato di attesa iniziale: l'app riceve l'operazione in attesa insieme a uno stato di attesa iniziale di done=null. Ciò indica che il file non è ancora pronto per il download e che lo stato dell'operazione è in attesa.

7. Chiama operations.get e verifica il risultato: l'app chiama get() agli intervalli consigliati per eseguire il polling del risultato dell'operazione e ottenere lo stato più recente di un'operazione a lunga esecuzione. Se viene restituito lo stato in attesa di done=false, l'app deve continuare a eseguire il polling finché l'operazione non restituisce lo stato completato (done=true). Per i file di grandi dimensioni, è necessario eseguire il polling più volte. Per ulteriori informazioni, vedi Ottenere i dettagli di un'operazione di lunga durata.

8. Controlla lo stato in attesa: se lo stato in attesa di done=true viene restituito dall'LRO, significa che il file è pronto per il download e che lo stato dell'operazione è completato.

9. Restituire l'operazione completata con l'URI di download: al termine dell'operazione LRO, l'API Drive restituisce l'URI di download e il file è ora disponibile per l'utente.

Scarica file

Per scaricare contenuti in un'operazione di lunga durata, utilizza il metodo download() nella risorsa files. Il metodo prende i parametri di query file_id, mime_type e revision_id:

• Obbligatorio. Il parametro di query file_id è l'ID del file da scaricare.

• Facoltativo. Il parametro di query mime_type indica il tipo MIME che deve essere utilizzato dal metodo. È disponibile solo quando scarichi contenuti multimediali non blob (ad esempio i documenti di Google Workspace). Per un elenco completo dei tipi MIME supportati, consulta Esportazione dei tipi MIME per i documenti Google Workspace.

  Se il tipo MIME non è impostato, il documento di Google Workspace viene scaricato con un tipo MIME predefinito. Per ulteriori informazioni, consulta la sezione Tipi MIME predefiniti.

• Facoltativo. Il parametro di query revision_id è l'ID revisione del file da scaricare. È disponibile solo quando scarichi file BLOB, Documenti Google e Fogli Google. Restituisce il codice di errore INVALID_ARGUMENT durante il download di una revisione specifica su file non supportati.

Il metodo download() è l'unico modo per scaricare i file Vids in formato MP4 ed è in genere il più adatto per scaricare la maggior parte dei file video.

I link per il download generati per Documenti o Fogli Google inizialmente riportano a un reindirizzamento. Fai clic sul nuovo link per scaricare il file.

Sia la richiesta al metodo download() che avvia l'operazione LRO sia la richiesta per recuperare l'URI di download finale devono utilizzare le chiavi delle risorse. Per ulteriori informazioni, vedi Accedere ai file di Drive condivisi tramite link utilizzando le chiavi di risorsa.

Il protocollo di richiesta è mostrato qui.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Sostituisci FILE_ID con il fileId del file che vuoi scaricare.

Tipi MIME predefiniti

Se non viene impostato un tipo MIME durante il download di contenuti non blob, vengono assegnati i seguenti tipi MIME predefiniti:

Scarica risposta

Quando chiami il metodo download(), il corpo della risposta è costituito da una risorsa che rappresenta un'operazione a lunga esecuzione. In genere, il metodo restituisce un link per scaricare i contenuti del file.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

Questo output include i seguenti valori:

• RESOURCE_KEY: una chiave della risorsa aiuta a proteggere il file da accessi indesiderati. Per ulteriori informazioni, vedi Accedere ai file di Drive condivisi tramite link utilizzando le chiavi di risorsa.

• NAME: il nome assegnato dal server.

• DOWNLOAD_URI: l'URI di download finale del file.

Tieni presente che il campo partialDownloadAllowed indica se è consentito un download parziale. True quando si scaricano i contenuti del file blob.

Visualizzare i dettagli di un'operazione a lunga esecuzione

Le operazioni a lunga esecuzione sono chiamate di metodi che potrebbero richiedere molto tempo per essere completate. In genere, le operazioni di download appena create vengono inizialmente riportate in stato di attesa (done=null), in particolare per i file Vids.

Puoi utilizzare la risorsa operations fornita dall'API Drive per controllare lo stato dell'elaborazione LRO includendo il nome univoco assegnato dal server.

Il metodo get() recupera lo stato più recente di un'operazione a lunga esecuzione in modo asincrono. I client possono utilizzare questo metodo per eseguire il polling del risultato dell'operazione a intervalli come consigliato dal servizio API.

Eseguire il polling di un'operazione a lunga esecuzione

Per eseguire il polling di un LRO disponibile, chiama ripetutamente il metodo get() fino al completamento dell'operazione. Utilizza un backoff esponenziale tra ogni richiesta di polling, ad esempio 10 secondi.

Un LRO rimane disponibile per un minimo di 12 ore, ma in alcuni casi può persistere anche più a lungo. Questa durata è soggetta a modifiche e può variare in base al tipo di file. Una volta scaduta la risorsa, è necessaria una nuova richiesta del metodo download().

Eventuali richieste a get() devono utilizzare le chiavi delle risorse. Per ulteriori informazioni, consulta Accedere ai file di Drive condivisi tramite link utilizzando le chiavi delle risorse.

I protocolli di richiesta sono mostrati qui.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Tieni presente che name viene restituito solo nella risposta a una richiesta download(). Non esiste un altro modo per recuperarlo perché l'API Drive non supporta il metodo List(). Se il valore name viene perso, devi generare una nuova risposta chiamando di nuovo la richiesta del metodo download().

La risposta a una richiesta get() è costituita da una risorsa che rappresenta un'operazione a lunga esecuzione. Per ulteriori informazioni, vedi Download response.

Quando la risposta contiene uno stato di completamento (done=true), l'operazione a lunga esecuzione è terminata.

Scaricare una revisione

Puoi utilizzare il valore del campo headRevisionId della risorsa files per scaricare l'ultima revisione. Viene recuperata la revisione corrispondente ai metadati del file recuperato in precedenza. Per scaricare i dati di tutte le revisioni precedenti del file ancora archiviate nel cloud, puoi chiamare il metodo list() della risorsa revisions con il parametro fileId. Verranno restituiti tutti i revisionIds nel file.

Per scaricare i contenuti della revisione dei file BLOB, devi chiamare il metodo get() sulla risorsa revisions con l'ID del file da scaricare, l'ID della revisione e il parametro URL alt=media. Il parametro URL alt=media indica al server che è stato richiesto il download di contenuti come formato di risposta alternativo.

Le revisioni di Documenti, Fogli, Presentazioni e Video Google non possono essere scaricate utilizzando il metodo get() con l'URL alt=media . In caso contrario, viene generato un fileNotDownloadable errore.

Il parametro URL alt=media è un parametro di sistema disponibile in tutte le API REST di Google. Se utilizzi una libreria client per l'API Drive, non è necessario impostare esplicitamente questo parametro.

Il protocollo di richiesta è mostrato qui.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Sostituisci quanto segue:

• FILE_ID: il fileId del file che vuoi scaricare.
• REVISION_ID: il revisionId della revisione che vuoi scaricare.

Le revisioni di Documenti, Disegni e Presentazioni Google incrementano automaticamente i numeri di revisione. Tuttavia, la serie di numeri potrebbe avere lacune se le revisioni vengono eliminate, pertanto non dovresti fare affidamento sui numeri sequenziali per recuperare le revisioni.

Risolvere i problemi relativi alle richieste LRO

Quando un LRO non va a buon fine, la sua risposta include un codice di errore canonical di Google Cloud.

La tabella seguente fornisce una spiegazione della causa di ciascun codice e un consiglio su come gestirlo. Per molti errori, l'azione consigliata è riprovare a effettuare la richiesta utilizzando il backoff esponenziale.

Puoi scoprire di più su questo modello di errore e su come utilizzarlo nella guida alla progettazione delle API.

Argomenti correlati

• Scaricare ed esportare file
• Gestire le revisioni dei file