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 una risorsa operations al client. 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(). Gli LRO
nell'API Drive aderiscono al pattern di progettazione 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.
Chiama
files.download: quando l'app chiama il metododownload(), avvia la richiesta di download dell'API Drive per il file. Per ulteriori informazioni, vedi Scaricare file.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.
Avvia download: viene inviata una richiesta all'API Drive per avviare il download del file. La richiesta potrebbe essere inviata a Google Vids o ad altri contenuti di Google Workspace.
Avvia LRO: viene avviata un'operazione a lunga esecuzione che gestisce il processo di download.
Restituzione in attesa di operazione: l'API Drive restituisce un'operazione in attesa contenente informazioni sull'utente che ha effettuato la richiesta e diversi campi di metadati del file.
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.Chiama
operations.gete verifica il risultato: l'app chiamaget()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 didone=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.Controlla lo stato in attesa: se lo stato in attesa di
done=trueviene restituito dall'LRO, significa che il file è pronto per il download e che lo stato dell'operazione è completo.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_typeindica 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, vedi 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 erroreINVALID_ARGUMENTdurante 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.
Una richiesta al metodo download() che avvia l'LRO e la richiesta di
recuperare l'URI del download finale devono utilizzare chiavi delle risorse. Per ulteriori informazioni, vedi Accedere ai file di Drive condivisi tramite link utilizzando le chiavi di risorsa.
Il protocollo della richiesta è mostrato qui.
POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/downloadSostituisci 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 | PN | image/png | .png |
| Moduli Google | ZIP | application/zip | .zip |
| Fogli Google | Microsoft Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| Google Sites | Testo non elaborato | text/raw | .txt |
| Presentazioni Google | Microsoft PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| Google Vids | MP4 | application/mp4 | .mp4 |
| Jamboard | application/pdf |
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 metodo il cui completamento potrebbe richiedere molto tempo. 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 sondaggio su un'operazione a lunga esecuzione
Per eseguire il polling di un LRO disponibile, chiama ripetutamente il metodo get() fino al termine 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 più a lungo. Questa durata è soggetta a modifiche e può variare in base al tipo di file. Dopo la scadenza della risorsa, è necessaria una nuova richiesta del metodo download().
Eventuali richieste a get() dovrebbero utilizzare 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.
Chiamata al metodo
operations.get(name='NAME');
Sostituisci NAME con il nome assegnato dal server dell'operazione, come mostrato nella risposta alla richiesta di 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 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() è composta da una risorsa che rappresenta un'operazione a lunga esecuzione. Per ulteriori informazioni, vedi Scaricare la risposta.
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. Vengono restituiti tutti i valori revisionIds presenti 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 un 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=mediaSostituisci quanto segue:
- FILE_ID: il
fileIddel file che vuoi scaricare. - REVISION_ID: il
revisionIddella revisione che vuoi scaricare.
In Documenti, Disegni e Presentazioni Google, i numeri delle revisioni vengono incrementati automaticamente. 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 canonico 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 inviare 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.
| Codice | Enum | Descrizione | Azione consigliata |
|---|---|---|---|
| 1 | CANCELLED |
L'operazione è stata annullata, in genere dal chiamante. | Esegui di nuovo l'operazione. |
| 2 | UNKNOWN |
Questo errore potrebbe essere restituito quando un valore Status ricevuto da un altro spazio di indirizzi appartiene a uno spazio di errore non noto in questo spazio degli indirizzi. Se l'errore dell'API non restituisce informazioni sufficienti, l'errore potrebbe essere convertito in questo errore. |
Riprova con il backoff esponenziale. |
| 3 | INVALID_ARGUMENT |
Il client ha specificato un argomento non valido. Questo errore è diverso da FAILED_PRECONDITION. INVALID_ARGUMENT indica gli argomenti problematici indipendentemente dallo stato del sistema, ad esempio un nome file con formato non corretto. |
Non riprovare senza risolvere il problema. |
| 4 | DEADLINE_EXCEEDED |
La scadenza è scaduta prima del completamento dell'operazione. 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 corretta da un server potrebbe essere ritardata abbastanza a lungo prima della scadenza. | Riprova con il backoff esponenziale. |
| 5 | NOT_FOUND |
Alcune entità richieste, ad esempio una risorsa FHIR, non sono state trovate. | Non riprovare senza risolvere il problema. |
| 6 | ALREADY_EXISTS |
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 |
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 |
Una risorsa è stata esaurita, ad esempio una quota per progetto. | Riprova con il backoff esponenziale. La quota potrebbe diventare disponibile nel tempo. |
| 9 | FAILED_PRECONDITION |
L'operazione è stata rifiutata perché il sistema non si trova nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota oppure viene applicata un'operazione rmdir a una directory diversa. |
Non riprovare senza risolvere il problema. |
| 10 | ABORTED |
L'operazione è stata interrotta, in genere a causa di un problema di contemporaneità come un errore del controllo del sequencer o dell'interruzione di una transazione. | Riprova con il backoff esponenziale. |
| 11 | OUT_OF_RANGE |
È stato tentato di eseguire l'operazione oltre l'intervallo valido, ad esempio la ricerca o la lettura oltre il fine 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 |
L'operazione non è implementata o non è supportata/abilitata nell'API Drive. | Non riprovare. |
| 13 | INTERNAL |
Errori interni. Indica che si è verificato un errore imprevisto durante l'elaborazione nel sistema sottostante. | Riprova con il backoff esponenziale. |
| 14 | UNAVAILABLE |
L'API Drive non è disponibile. Molto probabilmente si tratta di una condizione transitoria, che può essere corretta tentando di nuovo con il backoff esponenziale. Tieni presente che non è sempre sicuro ritentare le operazioni non idempotenti. | Riprova con il backoff esponenziale. |
| 15 | DATA_LOSS |
Perdita di dati non recuperabili o danneggiamento dei dati. | Rivolgiti al tuo amministratore di sistema. L'amministratore di sistema potrebbe voler contattare un rappresentante dell'assistenza in caso di perdita o danneggiamento dei dati. |
| 16 | UNAUTHENTICATED |
La richiesta non ha credenziali di autenticazione valide per l'operazione. | Non riprovare senza risolvere il problema. |