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 vuoi mantenere aperto il thread di chiamata mentre l'attività è in esecuzione, in quanto offre un'esperienza utente scadente. È meglio invece restituire all'utente una sorta di promessa e invitarlo a riprovare in un secondo momento.
L'API Google Drive restituisce un'operazione di lunga durata ogni volta che chiami il metodo download sulla 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 API eseguendo il polling dell'operazione tramite il metodo get. Le operazioni LRO nell'API Drive rispettano
il pattern di progettazione LRO di Google Cloud.
Per saperne di più, consulta Operazioni di lunga durata.
Panoramica sulla procedura
Il seguente diagramma mostra i passaggi di alto livello del funzionamento del metodo file.download.
Chiamata
files.download: quando la tua app chiama il metododownload, avvia la richiesta di download dell'API Drive per il file. Per ulteriori informazioni, vedi Scaricare i 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 che non è ancora stata concessa, viene chiesto all'utente di accedere. La tua app chiede anche l'accesso con ambiti che specifichi quando configuri l'autenticazione.
Avvia download: viene inviata una richiesta dell'API Drive per avviare il download del file. La richiesta potrebbe essere rivolta a Google Vids o ad altri contenuti di Google Workspace.
Avvia LRO: inizia un'operazione a lunga esecuzione che gestisce il processo di download.
Restituisci 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.gete verifica il risultato: la tua app chiamagetagli 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 didone=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 ulteriori informazioni, vedi Visualizzare i dettagli di un'operazione a lunga esecuzione.Controlla lo stato in attesa: se viene restituito lo stato in attesa di
done=truedall'operazione LRO, significa che il file è pronto per il download e che lo stato dell'operazione è completato.Restituisci l'operazione completata con l'URI di download: una volta completata l'operazione LRO, l'API Drive restituisce l'URI di download e il file è ora disponibile per l'utente.
Scarica file
Per scaricare i contenuti nell'ambito di un'operazione di lunga durata, utilizza il metodo download nella risorsa
files. Il metodo accetta i parametri di ricerca di 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 il metodo deve utilizzare. È disponibile solo per il download di contenuti multimediali non blob (come i documenti Google Workspace). Per un elenco completo dei tipi MIME supportati, vedi Tipi MIME di esportazione per i documenti Google Workspace.Se il tipo MIME non è impostato, il documento 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 revisione del file da scaricare. È disponibile solo durante il download di 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 di download generati inizialmente per Documenti o Fogli Google restituiscono un reindirizzamento. Fai clic sul nuovo link per scaricare il file.
Una richiesta al metodo download che avvia l'operazione LRO e la richiesta per recuperare
l'URI di download finale devono utilizzare entrambe le chiavi delle risorse. Per saperne di più, vedi
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}/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 | PNG. | 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. Il metodo in genere 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 contribuisce a proteggere il file da accessi non autorizzati. Per ulteriori informazioni, vedi Accedere ai file di Drive condivisi tramite link utilizzando le chiavi 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. Vero 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 restituite
in stato di attesa (done=null), soprattutto per i file Vids.
Puoi utilizzare la risorsa operations fornita
dall'API Drive per controllare lo stato dell'operazione LRO di elaborazione
includendo il nome univoco assegnato dal server.
Il metodo get recupera in modo asincrono lo stato più recente di un'operazione a lunga esecuzione. 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'operazione LRO disponibile, chiama ripetutamente il metodo
get finché l'operazione non viene completata.
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 a seconda del tipo di file. Una volta scaduta la risorsa, è necessaria una nuova richiesta di metodo download.
Tutte le richieste a get devono utilizzare le chiavi delle risorse. Per saperne di più, vedi
Accedere ai file di Drive condivisi tramite link utilizzando le chiavi delle risorse.
I protocolli di richiesta vengono 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 name viene restituito solo nella risposta a una richiesta download.
Non esiste un altro modo per recuperarlo, in quanto 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 maggiori informazioni, vedi Scaricare
la risposta.
Quando la risposta contiene uno stato completato (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 sulla risorsa revisions con il parametro fileId. Vengono 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
alt=media URL indica al server che il download dei contenuti viene
richiesto come formato di risposta alternativo.
Le revisioni di Documenti, Fogli, Presentazioni e
Vids non possono essere scaricate utilizzando il metodo get con l'URL
alt=media . In caso contrario, genera un errore fileNotDownloadable.
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.
Le revisioni di Documenti, Disegni e Presentazioni Google aumentano automaticamente i numeri di revisione. Tuttavia, la serie di numeri potrebbe presentare lacune se le revisioni vengono eliminate, quindi non devi fare affidamento su numeri sequenziali per recuperare le revisioni.
Risolvere i problemi relativi alle operazioni a lunga esecuzione
Quando un'operazione di lunga durata non va a buon fine, la risposta include un codice di errore canonico di Google Cloud.
La tabella seguente fornisce una spiegazione della causa di ogni codice e un consiglio su come gestirlo. Per molti errori, l'azione consigliata è riprovare a inviare la richiesta utilizzando il backoff esponenziale.
Puoi leggere ulteriori informazioni 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 errori sconosciuto in questo spazio di indirizzi. Se l'errore API non restituisce informazioni sufficienti, 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 argomenti problematici indipendentemente dallo stato del sistema, ad esempio un nome file non valido. |
Non riprovare senza risolvere il problema. |
| 4 | DEADLINE_EXCEEDED |
La scadenza è terminata 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 riuscita da un server potrebbe essere stata ritardata abbastanza a lungo da far scadere il termine. | 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 |
Alcune risorse sono esaurite, 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 o un'operazione rmdir viene applicata a un elemento non di tipo directory. |
Non riprovare senza risolvere il problema. |
| 10 | ABORTED |
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 il backoff esponenziale. |
| 11 | OUT_OF_RANGE |
L'operazione è stata tentata oltre l'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 |
L'operazione non è implementata o non è supportata/abilitata nell'API Drive. | Non riprovare. |
| 13 | INTERNAL |
Errori interni. Ciò 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. Si tratta molto probabilmente di una condizione temporanea, che può essere corretta riprovando con un backoff esponenziale. Tieni presente che non è sempre sicuro riprovare le operazioni non idempotenti. | Riprova con il backoff esponenziale. |
| 15 | DATA_LOSS |
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 o danneggiamento dei dati. |
| 16 | UNAUTHENTICATED |
La richiesta non ha credenziali di autenticazione valide per l'operazione. | Non riprovare senza risolvere il problema. |