Gestione delle operazioni a lunga esecuzione

Un'operazione a lunga esecuzione (LRO) è un metodo API che richiede più tempo per essere completato rispetto a quanto appropriato per una risposta API. In genere, non è consigliabile mantenere aperto il thread di chiamata durante l'esecuzione dell'attività, in quanto offre una scarsa esperienza utente. È invece preferibile restituire all'utente un tipo di promessa e consentirgli di ricontrollare in un secondo momento.

L'API Google Drive restituisce un'operazione a lunga esecuzione ogni volta che chiami il download metodo sulla files risorsa per scaricare i contenuti di un file tramite l'API Drive o le relative librerie client.

Il metodo restituisce una risorsa operations a l client. Puoi utilizzare la risorsa operations per recuperare in modo asincrono lo stato del metodo API eseguendo il polling dell'operazione tramite il metodo get. Le operazioni a lunga esecuzione nell'API Drive rispettano il pattern di progettazione delle operazioni a lunga esecuzione di Google Cloud.

Per saperne di più, consulta Operazioni a lunga esecuzione.

Panoramica sulla procedura

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

**Figura 1.** Passaggi di alto livello per il metodo file.download.

Chiama files.download: quando la tua app chiama il metodo download, avvia la richiesta di download dell'API Drive per il file. Per saperne di più, consulta Scaricare file.
Richiedi autorizzazioni: la richiesta invia le credenziali di autenticazione all' API Drive. Se la tua app richiede la chiamata all'API Drive utilizzando l'autenticazione di un utente a cui non è ancora stata concessa, viene chiesto all'utente di accedere. La tua app chiede anche l'accesso con ambiti che specifichi durante la configurazione dell'autenticazione.
Avvia il download: viene effettuata una richiesta all'API Drive per avviare il download del file. La richiesta potrebbe essere rivolta a Google Vids o ad altri contenuti di Google Workspace.
Avvia l'operazione a lunga esecuzione: viene avviata un'operazione a lunga esecuzione che gestisce la procedura di download.
Restituisci l'operazione in attesa: l'API Drive restituisce un'operazione in attesa contenente informazioni sull'utente che effettua la richiesta e diversi campi di metadati dei file.
Stato iniziale in attesa: la tua app riceve l'operazione in attesa insieme a uno stato iniziale in attesa di done=null. Ciò indica che il file non è ancora pronto per il download e che lo stato dell'operazione è in attesa.
Chiama operations.get e verifica il risultato: la tua app chiama il metodo get agli intervalli consigliati per eseguire il polling del risultato dell'operazione e ottenere l'ultimo stato di un'operazione a lunga esecuzione. Se viene restituito lo stato in attesa di done=false, la tua app deve continuare a eseguire il polling finché l'operazione non restituisce lo stato completato (done=true). Per i file di grandi dimensioni, prevedi di eseguire il polling più volte. Per saperne di più, consulta Visualizzare i dettagli di un'operazione a lunga esecuzione.
Controlla lo stato in attesa: se lo stato in attesa di done=true viene restituito dall'operazione a lunga esecuzione, significa che il file è pronto per il download e che lo stato dell'operazione è completato.
Restituisci l'operazione completata con l'URI di download: al termine dell'operazione a lunga esecuzione, l'API Drive restituisce l'URI di download e il file è ora disponibile per l'utente.

Scaricare file

Per scaricare i contenuti nell'ambito di un'operazione a lunga esecuzione, utilizza il download metodo sulla files risorsa. Il metodo accetta i parametri file_id, mime_type e revision_id:

Obbligatorio. Il parametro del percorso file_id è l'ID del file da scaricare.
Facoltativo. Il parametro di query mime_type indica il tipo MIME che il metodo deve utilizzare. È disponibile solo quando si scaricano contenuti multimediali non blob (ad esempio documenti di Google Workspace). Per un elenco completo dei tipi MIME supportati, consulta Tipi MIME di esportazione per i documenti di Google Workspace.

Se il tipo MIME non è impostato, il documento di Google Workspace viene scaricato con un tipo MIME predefinito. Per saperne di più, consulta Tipi MIME predefiniti.
Facoltativo. Il parametro di query revision_id è l'ID della revisione del file da scaricare. È disponibile solo quando si scaricano file blob, Documenti Google e Fogli Google. Restituisce il codice di errore INVALID_ARGUMENT quando si scarica 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. Se tenti di esportare i file di Google Vids, ricevi un fileNotExportable errore.

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

Sia la richiesta al metodo download che avvia l'operazione a lunga esecuzione sia la richiesta per recuperare l'URI di download finale devono utilizzare le chiavi delle risorse. Per saperne di più, consulta Accedere ai file di Drive condivisi tramite link utilizzando le chiavi delle risorse.

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:

Tipo di documento	Formato	Tipo MIME	Estensione del file
Google Apps Script	JSON	application/vnd.google-apps.script+json	.json
Documenti Google	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Disegni Google	PNG	image/png	.png
Moduli Google	ZIP	application/zip	.zip
Fogli Google	Microsoft Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
Google Sites	Testo normale	text/raw	.txt
Presentazioni Google	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Google Vids	MP4	video/mp4	.mp4
Jamboard	PDF	application/pdf	.pdf

Scarica risposta

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

name

{
  "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 ti aiuta a proteggere il file da accessi non intenzionali. Per saperne di più, consulta Accedere ai file di Drive condivisi tramite link utilizzando le chiavi delle risorse.
NAME: il nome assegnato dal server.
DOWNLOAD_URI: l'URI di download finale per il file.

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

Visualizzare i dettagli di un'operazione a lunga esecuzione

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

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

Il metodo get recupera in modo asincrono l'ultimo stato di un' operazione a lunga esecuzione. I client possono utilizzare questo metodo per eseguire il polling del risultato dell'operazione a intervalli come suggerito dal servizio API.

Eseguire il polling di un'operazione a lunga esecuzione

Per eseguire il polling di un'operazione a lunga esecuzione disponibile, chiama ripetutamente il get metodo finché l'operazione non viene completata. Utilizza un backoff esponenziale tra ogni richiesta di polling, ad esempio 10 secondi.

Un'operazione a lunga esecuzione rimane disponibile per un minimo di 12 ore, ma in alcuni casi può persistere più a lungo. Questa durata è soggetta a modifiche e può variare a seconda dei tipi di file. Una volta scaduta la risorsa, è necessaria una nuova richiesta del metodo download.

Tutte le richieste a get devono utilizzare le chiavi delle risorse. Per saperne di più, consulta Accedere ai file di Drive condivisi tramite link utilizzando le chiavi delle risorse.

I protocolli di richiesta sono mostrati qui.

Chiamata al metodo

operations.get(name='NAME');

Sostituisci NAME con il nome assegnato dal server all'operazione, come mostrato nella risposta alla richiesta del metodo download.

curl

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

Sostituisci NAME con il nome assegnato dal server all'operazione, come mostrato nella risposta alla richiesta del metodo download.

Il comando utilizza il percorso /drive/v3/operations/NAME.

Tieni presente che il name viene restituito solo nella risposta a una richiesta download. Non esiste un altro modo per recuperarlo, poiché 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 saperne di più, consulta Scarica risposta.

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

Scaricare una revisione

Puoi utilizzare il valore del headRevisionId campo della risorsa files per scaricare l'ultima revisione. In questo modo 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 list metodo sulla risorsa revisions con il parametro fileId. In questo modo vengono restituiti tutti i revisionIds nel file.

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

Le revisioni di Documenti, Fogli, Presentazioni e Vids 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 devi 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 presentare delle lacune se le revisioni vengono eliminate, quindi non devi fare affidamento sui numeri sequenziali per recuperare le revisioni.

Risolvere i problemi relativi alle operazioni a lunga esecuzione

Quando un'operazione a lunga esecuzione non va a buon fine, la risposta include un codice di errore canonico di Google Cloud.

La tabella seguente mostra ogni codice di errore, il codice di stato HTTP mappato, una descrizione e un consiglio su come gestire il codice di errore. Per molti errori, il comportamento consigliato è riprovare a inviare la richiesta utilizzando il backoff esponenziale.

Per ulteriori informazioni su questo modello di errore e su come gestirlo, consulta la Guida alla progettazione delle API.

Codice	Enum	Codice di stato HTTP	Descrizione	Comportamento consigliato
1	`CANCELLED`	`499 Client Closed Request`	L'operazione è stata annullata, in genere dal chiamante.	Esegui di nuovo l'operazione.
2	`UNKNOWN`	`500 Internal Server Error`	Questo errore potrebbe essere restituito quando un valore `Status` ricevuto da un altro spazio di indirizzi appartiene a uno spazio di errore sconosciuto in questo spazio di indirizzi. Se l'errore dell'API non restituisce informazioni sufficienti, l'errore potrebbe essere convertito in questo errore.	Riprova con un backoff esponenziale.
3	`INVALID_ARGUMENT`	`400 Bad Request`	Il client ha specificato un argomento non valido. Questo errore è diverso da `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indica argomenti problematici indipendentemente dallo stato del sistema, ad esempio un nome file non valido.	Non riprovare senza risolvere il problema.
4	`DEADLINE_EXCEEDED`	`504 Gateway Timeout`	La scadenza è trascorsa prima che l'operazione potesse essere completata. Per le operazioni che modificano lo stato del sistema, questo errore potrebbe essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta positiva da un server potrebbe essere stata ritardata abbastanza da far scadere la scadenza.	Riprova con un backoff esponenziale.
5	`NOT_FOUND`	`404 Not Found`	Non è stata trovata un'entità richiesta, ad esempio una risorsa FHIR.	Non riprovare senza risolvere il problema.
6	`ALREADY_EXISTS`	`409 Conflict`	L'entità che un client ha tentato di creare, ad esempio un'istanza DICOM, esiste già.	Non riprovare senza risolvere il problema.
7	`PERMISSION_DENIED`	`403 Forbidden`	Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata. Questo codice di errore non implica che la richiesta sia valida, che l'entità richiesta esista o che soddisfi altre precondizioni.	Non riprovare senza risolvere il problema.
8	`RESOURCE_EXHAUSTED`	`429 Too Many Requests`	È stata esaurita una risorsa, ad esempio una quota per progetto.	Riprova con un backoff esponenziale. La quota potrebbe diventare disponibile nel tempo.
9	`FAILED_PRECONDITION`	`400 Bad Request`	La richiesta è stata rifiutata perché il sistema non è nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota oppure un'operazione `rmdir` viene applicata a una directory non vuota.	Non riprovare senza risolvere il problema.
10	`ABORTED`	`409 Conflict`	L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un errore di controllo del sequencer o un'interruzione della transazione.	Riprova con un backoff esponenziale.
11	`OUT_OF_RANGE`	`400 Bad Request`	L'operazione è stata tentata al di fuori dell'intervallo valido, ad esempio la ricerca o la lettura oltre la fine del file. A differenza di `INVALID_ARGUMENT`, questo errore indica un problema che potrebbe essere risolto se lo stato del sistema cambia.	Non riprovare senza risolvere il problema.
12	`UNIMPLEMENTED`	`501 Not Implemented`	L'operazione non è implementata o non è supportata/abilitata nell'API Drive.	Non riprovare.
13	`INTERNAL`	`500 Internal Server Error`	Errori interni. Indica che si è verificato un errore imprevisto durante l'elaborazione nel sistema sottostante.	Riprova con un backoff esponenziale.
14	`UNAVAILABLE`	`503 Service Unavailable`	L'API Drive non è disponibile. Si tratta molto probabilmente di una condizione temporanea, che può essere corretta riprovando con un backoff esponenziale. Tieni presente che non è sempre sicuro riprovare a eseguire operazioni non idempotenti.	Riprova con un backoff esponenziale.
15	`DATA_LOSS`	`500 Internal Server Error`	Perdita o danneggiamento dei dati non recuperabili.	Rivolgiti al tuo amministratore di sistema. L'amministratore di sistema potrebbe voler contattare un rappresentante dell'assistenza in caso di perdita di dati o danneggiamento.
16	`UNAUTHENTICATED`	`401 Unauthorized`	La richiesta non ha credenziali di autenticazione valide per l'operazione.	Non riprovare senza risolvere il problema.

Scaricare ed esportare file