L'API Google Drive ti consente di caricare i dati dei file quando crei o aggiorni una File
. Per informazioni su come creare un file contenente solo metadati, ad esempio una cartella, consulta la sezione Creare file di soli metadati.
Puoi eseguire tre tipi di caricamenti:
Caricamento semplice (
uploadType=media
): utilizza questo tipo di caricamento per trasferire un file multimediale di piccole dimensioni (massimo 5 MB) senza fornire metadati. Per eseguire un caricamento semplice, consulta Eseguire un caricamento semplice.Caricamento multiparte (
uploadType=multipart
): "Utilizza questo tipo di caricamento per trasferire in un'unica richiesta un file di piccole dimensioni (massimo 5 MB) insieme ai metadati che descrivono il file. Per eseguire un caricamento con più parti, consulta Eseguire un caricamento multiparte.Caricamento ripristinabile (
uploadType=resumable
): utilizza questo tipo di caricamento per i file di grandi dimensioni (maggiori di 5 MB) e quando c'è un'alta probabilità di interruzione della rete, ad esempio quando crei un file da un'app mobile. I caricamenti ripristinabili sono un'ottima scelta anche per la maggior parte delle applicazioni, perché funzionano anche per file di piccole dimensioni al costo minimo di una richiesta HTTP aggiuntiva per caricamento. Per eseguire un caricamento ripristinabile, consulta l'articolo Eseguire un caricamento ripristinabile.
Le librerie client delle API di Google implementano almeno uno di questi tipi di caricamenti. Per ulteriori dettagli su come utilizzare ciascuno di questi tipi, consulta la documentazione relativa alla libreria client.
Usa PATCH
rispetto a PUT
Ti ricordiamo che il verbo HTTP PATCH
supporta un aggiornamento parziale delle risorse del file, mentre il verbo HTTP PUT
supporta la sostituzione completa della risorsa. Tieni presente che PUT
può introdurre modifiche che provocano un errore quando aggiunge un nuovo campo a una risorsa esistente.
Quando carichi una risorsa di file, segui queste linee guida:
- Utilizza il verbo HTTP documentato nel riferimento dell'API per la richiesta iniziale di un caricamento ripristinabile o per l'unica richiesta di un caricamento semplice o multiparte.
- Utilizza
PUT
per tutte le richieste successive di un caricamento ripristinabile una volta avviata la richiesta. Queste richieste caricano contenuti, a prescindere dal metodo chiamato.
Eseguire un caricamento semplice
Per eseguire un semplice caricamento, utilizza il metodo files.create
con uploadType=media
.
Di seguito viene illustrato come eseguire un semplice caricamento:
HTTP
Crea una richiesta
POST
all'URI /upload del metodo con il parametro di queryuploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Aggiungi i dati del file al corpo della richiesta.
Aggiungi queste intestazioni HTTP:
Content-Type
. Imposta il tipo multimediale MIME dell'oggetto che viene caricato.Content-Length
. Imposta il numero di byte caricati. Se utilizzi la codifica per il trasferimento in blocchi, questa intestazione non è obbligatoria.
Invia la richiesta. Se la richiesta ha esito positivo, il server restituisce il codice di stato
HTTP 200 OK
insieme ai metadati del file. {HTTP}
Quando esegui un caricamento semplice, vengono creati i metadati di base e alcuni attributi vengono dedotti dal file, come il tipo MIME o modifiedTime
. Puoi utilizzare un semplice caricamento nei casi in cui tu abbia file di piccole dimensioni e i metadati dei file non siano importanti.
Esecuzione di un caricamento multiparte
Una richiesta di caricamento multiparte consente di caricare metadati e dati nella stessa richiesta. Utilizza questa opzione se i dati inviati sono sufficientemente ridotti da poter essere caricati di nuovo nella loro interezza, in caso di problemi di connessione.
Per eseguire un caricamento con più parti, utilizza il metodo files.create
con uploadType=multipart
.
Di seguito viene illustrato come eseguire un caricamento multiparte:
Java
Python
Node.js
PHP
.NET
HTTP
Crea una richiesta
POST
all'URI /upload del metodo con il parametro di queryuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Crea il corpo della richiesta. Formatta il corpo in base al tipo di contenuti multipart/related RFC 2387, che contiene due parti:
- Metadati. I metadati devono essere inseriti per primi e devono avere un'intestazione
Content-Type
impostata suapplication/json;
charset=UTF-8
. Aggiungi i metadati del file in formato JSON. - Contenuti multimediali. I contenuti multimediali devono essere secondi e devono avere un'intestazione
Content-Type
di qualsiasi tipo MIME. Aggiungi i dati del file alla parte multimediale.
Identifica ogni parte con una stringa di confine, preceduta da due trattini. Inoltre, aggiungi due trattini dopo la stringa di confine finale.
- Metadati. I metadati devono essere inseriti per primi e devono avere un'intestazione
Aggiungi queste intestazioni HTTP di primo livello:
Content-Type
. Impostalo sumultipart/related
e includi la stringa di confine che stai utilizzando per identificare le diverse parti della richiesta. Ad esempio:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Impostalo sul numero totale di byte nel corpo della richiesta.
Invia la richiesta.
Per creare o aggiornare solo la parte dei metadati, senza i dati associati, invia una richiesta POST
o PATCH
all'endpoint della risorsa standard:
https://www.googleapis.com/drive/v3/files
Se la richiesta ha esito positivo,
il server restituisce il codice di stato HTTP 200 OK
insieme ai metadati
del file.
Durante la creazione dei file, è necessario specificare un'estensione nel campo name
del file. Ad esempio, quando crei un file JPEG di foto, potresti specificare qualcosa come "name": "photo.jpg"
nei metadati. Le chiamate successive a files.get
restituiscono la proprietà fileExtension
di sola lettura
contenente l'estensione originariamente specificata nel campo name
.
Eseguire un caricamento ripristinabile
Un caricamento ripristinabile ti consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione ha interrotto il flusso dei dati. Poiché non è necessario riavviare i caricamenti di file di grandi dimensioni fin dall'inizio, i caricamenti ripristinabili possono anche ridurre l'utilizzo della larghezza di banda in caso di errore di rete.
I caricamenti ripristinabili sono utili quando le dimensioni dei file possono variare notevolmente o quando esiste un limite di tempo fisso per le richieste (ad esempio le attività in background del sistema operativo mobile e determinate richieste di App Engine). Puoi anche utilizzare caricamenti ripristinabili nelle situazioni in cui vuoi mostrare una barra di avanzamento.
Un caricamento ripristinabile è costituito da diversi passaggi generali:
- Invia la richiesta iniziale e recupera l'URI della sessione ripristinabile.
- Caricare i dati e monitorare lo stato di caricamento.
- (Facoltativo) Se il caricamento è disturbato, riprendilo.
Invia la richiesta iniziale
Per avviare un caricamento ripristinabile, utilizza il metodo files.create
con uploadType=resumable
.
HTTP
Crea una richiesta
POST
all'URI /upload del metodo con il parametro di queryuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Se la richiesta di avvio ha esito positivo, la risposta include un codice di stato HTTP
200 OK
. Inoltre, include un'intestazioneLocation
che specifica l'URI della sessione ripristinabile:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Salva l'URI della sessione ripristinabile in modo da poter caricare i dati del file ed eseguire query sullo stato di caricamento. Un URI di sessione ripristinabile scade dopo una settimana.
Se disponi di metadati per il file, aggiungili al corpo della richiesta in formato JSON. In caso contrario, lascia vuoto il corpo della richiesta.
Aggiungi queste intestazioni HTTP:
X-Upload-Content-Type
. Facoltativa. Impostato sul tipo MIME dei dati del file, che viene trasferito nelle richieste successive. Se il tipo MIME dei dati non è specificato nei metadati o tramite questa intestazione, l'oggetto viene pubblicato comeapplication/octet-stream.
X-Upload-Content-Length
. Facoltativa. Impostato sul numero di byte dei dati del file, che vengono trasferiti nelle richieste successive.Content-Type
. Obbligatorio se disponi di metadati per il file. Imposta suapplication/json;
charset=UTF-8
.Content-Length
. Obbligatorio, a meno che non utilizzi la codifica di trasferimento in blocchi. Impostalo sul numero di byte nel corpo di questa richiesta iniziale.
Invia la richiesta. Se la richiesta di avvio della sessione ha esito positivo, la risposta include un codice di stato
200 OK HTTP
. Inoltre, la risposta include un'intestazioneLocation
che specifica l'URI della sessione ripristinabile. Utilizza l'URI di sessione ripristinabile per caricare i dati del file ed eseguire query sullo stato del caricamento. Un URI di sessione ripristinabile scade dopo una settimana.Copia e salva l'URL della sessione ripristinabile.
Vai alla sezione Caricare i contenuti.
Carica i contenuti
Esistono due modi per caricare un file con una sessione ripristinabile:
- Carica i contenuti in una singola richiesta: utilizza questo approccio quando il file può essere caricato in una singola richiesta, se non esiste un limite di tempo fisso per ogni singola richiesta o se non è necessario visualizzare un indicatore di avanzamento del caricamento. Questo approccio è migliore perché richiede meno richieste e migliora le prestazioni.
Carica i contenuti in più blocchi: utilizza questo approccio se devi ridurre la quantità di dati trasferiti in ogni singola richiesta. Potrebbe essere necessario ridurre i dati trasferiti quando esiste un limite di tempo fisso per le singole richieste, come può accadere per determinate classi di richieste di App Engine. Questo approccio è utile anche se devi fornire un indicatore personalizzato per mostrare l'avanzamento del caricamento.
HTTP - richiesta singola
- Crea una richiesta
PUT
all'URI della sessione ripristinabile. - Aggiungi i dati del file al corpo della richiesta.
- Aggiungi un'intestazione HTTP Content-Length, impostata sul numero di byte nel file.
- Invia la richiesta. Se la richiesta di caricamento viene interrotta o se ricevi una risposta
5xx
, segui la procedura descritta in Riprendere un caricamento interrotto.
HTTP - richieste multiple
Crea una richiesta
PUT
all'URI della sessione ripristinabile.Aggiungi i dati del blocco al corpo della richiesta. Crea blocchi di dimensioni multiple di 256 kB (256 x 1024 byte), ad eccezione del blocco finale che completa il caricamento. Mantieni le dimensioni del blocco il più possibile in modo che il caricamento sia efficace.
Aggiungi queste intestazioni HTTP:
Content-Length
. Imposta il numero di byte nel blocco attuale.Content-Range
. Impostala in modo che mostri i byte del file che carichi. Ad esempio,Content-Range: bytes 0-524287/2000000
mostra che hai caricato i primi 524.288 byte (256 x 1024 x 2) in un file di 2.000.000 di byte.
Invia la richiesta ed elabora la risposta. Se la richiesta di caricamento viene interrotta o se ricevi una risposta
5xx
, segui la procedura descritta in Riprendere un caricamento interrotto.Ripeti i passaggi da 1 a 4 per ogni blocco rimasto nel file. Utilizza l'intestazione
Range
nella risposta per determinare da dove iniziare il blocco successivo. Non dare per scontato che il server abbia ricevuto tutti i byte inviati nella richiesta precedente.
Al termine del caricamento del file, riceverai una risposta 200 OK
o
201 Created
, insieme a tutti i metadati associati alla risorsa.
Riprendere un caricamento interrotto
Se una richiesta di caricamento viene interrotta prima di una risposta o se ricevi una risposta 503
Service Unavailable
, devi riprendere il caricamento interrotto.
HTTP
Per richiedere lo stato di caricamento, crea una richiesta
PUT
vuota all'URI della sessione ripristinabile.Aggiungi un'intestazione
Content-Range
per indicare che la posizione corrente nel file è sconosciuta. Ad esempio, impostaContent-Range
su*/2000000
se la lunghezza totale del file è di 2.000.000 di byte. Se non conosci la dimensione intera del file, impostaContent-Range
su*/*
.Invia la richiesta.
Elabora la risposta:
- Una risposta
200 OK
o201 Created
indica che il caricamento è stato completato e non sono necessarie ulteriori azioni. - Una risposta
308 Resume Incomplete
indica che devi continuare per caricare il file. - Una risposta
404 Not Found
indica che la sessione di caricamento è scaduta e il caricamento deve essere riavviato dall'inizio.
- Una risposta
Se hai ricevuto una risposta
308 Resume Incomplete
, elabora l'intestazioneRange
della risposta per determinare quali byte sono stati ricevuti dal server. Se la risposta non ha un'intestazioneRange
, non sono stati ricevuti byte. Ad esempio, un'intestazioneRange
dibytes=0-42
indica che sono stati ricevuti i primi 43 byte del file e che il blocco successivo da caricare inizia con il byte 44.Ora che sai dove riprendere il caricamento, continua a caricare il file iniziando con il byte successivo. Includi un'intestazione
Content-Range
per indicare la parte del file che invii. Ad esempio,Content-Range: bytes 43-1999999
indica che invii i byte da 44 a 2.000.000.
Gestire gli errori di caricamento dei contenuti multimediali
Quando carichi contenuti multimediali, segui queste best practice per gestire gli errori:
- Per gli errori
5xx
, riprendi o riprova i caricamenti che non riescono a causa di interruzioni della connessione. Per ulteriori informazioni sulla gestione degli errori5xx
, consulta Errori 500, 502, 503, 504. - Per
403 rate limit
errori, riprova a eseguire il caricamento. Per ulteriori informazioni sulla gestione degli errori403 rate limit
, consulta Errore 403:rateLimitExceeded
. - Per eventuali errori
4xx
(incluso403
) durante un caricamento ripristinabile, riavvia il caricamento. Questi errori indicano che la sessione di caricamento è scaduta e devono essere riavviati richiedendo un nuovo URI di sessione. Anche le sessioni di caricamento scadono dopo una settimana di inattività.
Importa nei tipi di Documenti Google
Quando crei un file in Drive, ti consigliamo di convertirlo in un tipo di file di Google Workspace, come Documenti o Fogli Google. Ad esempio, potresti voler trasformare un documento dal tuo elaboratore di testi preferito in Documenti per sfruttarne le funzionalità.
Per convertire un file in un tipo di file specifico di Google Workspace, specifica il mimeType
di Google Workspace durante la creazione del file.
Di seguito viene mostrato come convertire un file CSV in un foglio di Google Workspace:
Java
Python
Node.js
PHP
.NET
Per verificare se è disponibile una conversione, controlla l'array importFormats
della risorsa about
prima di creare il file.
Le conversioni supportate sono disponibili in modo dinamico in questo array. Alcuni dei formati di importazione più comuni sono:
Da | To |
---|---|
Microsoft Word, testo OpenDocument, HTML, RTF, testo normale | Documenti Google |
Microsoft Excel, OpenDocument sheet, CSV, TSV, testo normale | Fogli Google |
Microsoft PowerPoint, OpenDocument presentazione | Presentazioni Google |
JPEG, PNG, GIF, BMP, PDF | Documenti Google (incorpora l'immagine in un documento) |
Testo normale (tipo MIME speciale), JSON | Google Apps Script |
Quando carichi e converti i contenuti multimediali durante una richiesta update
in un file di Documenti, Fogli o Presentazioni, vengono sostituiti tutti i contenuti del documento.
Quando converti un'immagine in Documenti, Drive usa
il riconoscimento ottico dei caratteri (OCR) per convertire l'immagine in testo. Puoi
migliorare la qualità dell'algoritmo OCR specificando il codice lingua BCP
47 applicabile
nel
parametro
ocrLanguage
. Il testo estratto viene visualizzato nel documento accanto all'immagine incorporata.
Utilizza un ID pregenerato per caricare file
L'API Drive consente di recuperare un elenco di ID file pregenerati che vengono utilizzati per caricare e creare risorse. Le richieste di caricamento e creazione di file
possono usare questi ID pregenerati. Imposta il campo id
nei metadati del file.
Per creare ID pregenerati, chiama files.generateIds
con il numero di ID da creare.
Puoi riprovare in sicurezza i caricamenti con ID pregenerati in caso di timeout o errore del server indeterminato. Se il file è stato creato correttamente, i tentativi successivi restituiscono un errore HTTP 409
e non creano file duplicati.
Definisci testo indicizzabile per tipi di file sconosciuti
Gli utenti possono utilizzare l'interfaccia utente di Drive per trovare i contenuti dei documenti. Puoi anche utilizzare files.list
e il campo fullText
per cercare contenuti dalla tua app. Per ulteriori informazioni, vedi Cercare file e cartelle.
Drive indicizza automaticamente i documenti per la ricerca quando riconosce il tipo di file, inclusi documenti di testo, PDF, immagini con testo e altri tipi comuni. Se l'app salva altri tipi di file (ad esempio disegni, video e scorciatoie), puoi migliorarne la rilevabilità fornendo testo indicizzabile nel campo contentHints.indexableText
del file.
Per ulteriori informazioni sul testo indicizzabile, consulta Gestire i metadati dei file.