L'API Google Drive ti consente di caricare i dati dei file quando crei o aggiorni un
File
Per informazioni su come creare un
ad esempio una cartella, consulta l'articolo Creare file di soli metadati.
Puoi eseguire tre tipi di caricamenti:
Caricamento semplice (
uploadType=media
): utilizza questo tipo di caricamento per trasferire una un file multimediale di piccole dimensioni (massimo 5 MB) senza fornire metadati. Per eseguire un Caricamento semplice, consulta l'articolo Eseguire un caricamento semplice.Caricamento multiparte (
uploadType=multipart
): "Utilizza questo tipo di caricamento per trasferire un file di piccole dimensioni (massimo 5 MB) insieme ai metadati che descrivono in un'unica richiesta. Per eseguire un caricamento di più parti, consulta la sezione Eseguire un caricamento multiparte.Caricamento ripristinabile (
uploadType=resumable
): utilizza questo tipo di caricamento per file di grandi dimensioni (superiori a 5 MB) e quando c'è un'elevata probabilità che la rete ad esempio durante la creazione di un file da un'app mobile. Ripristinabili i caricamenti sono un'ottima scelta anche per la maggior parte delle applicazioni, perché funzionano per file di piccole dimensioni al costo minimo di una richiesta HTTP aggiuntiva per caricamento. Per eseguire un caricamento ripristinabile, consulta Eseguire un caricamento ripristinabile. caricamento.
Le librerie client delle API di Google implementano almeno uno di questi tipi di caricamenti. Fai riferimento alla libreria client documentazione per ulteriori dettagli su come utilizzano ciascuno dei tipi.
Utilizza PATCH
rispetto a PUT
Ti ricordiamo che il verbo HTTP PATCH
supporta un aggiornamento parziale delle risorse dei file
mentre il verbo HTTP PUT
supporta la sostituzione completa delle risorse. Tieni presente che PUT
possono introdurre modifiche che provocano un errore quando si aggiunge un nuovo campo a una risorsa esistente.
Quando carichi una risorsa file, segui queste linee guida:
- Utilizza il verbo HTTP documentato nel riferimento 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 che la richiesta è stata avviata. Queste richieste caricano contenuti, indipendentemente viene chiamato.
Eseguire un caricamento semplice
Per eseguire un caricamento semplice, utilizza
Metodo files.create
con
uploadType=media
.
Di seguito viene illustrato come eseguire un caricamento semplice:
HTTP
Crea una richiesta
POST
all'URI /upload del metodo con la query parametro diuploadType=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
. Impostato sul tipo multimediale MIME dell'oggetto caricato.Content-Length
. Impostato sul numero di byte caricati. Se utilizzi per il trasferimento a 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, ad esempio il tipo MIME o modifiedTime
. Puoi utilizzare la modalità
un semplice caricamento nei casi in cui siano presenti file di piccole dimensioni e metadati dei file
importanti.
Eseguire un caricamento multiparte
Una richiesta di caricamento multiparte ti consente di caricare metadati e dati nello stesso richiesta. Utilizza questa opzione se i dati inviati sono sufficientemente ridotti per essere caricati di nuovo. completamente, in caso di problemi di connessione.
Per eseguire un caricamento multiparte, utilizza il metodo
Metodo files.create
con
uploadType=multipart
.
Di seguito viene illustrato come eseguire un caricamento con più parti:
Java
Python
Node.js
PHP
.NET
HTTP
Crea una richiesta
POST
all'URI /upload del metodo con la query parametro diuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Crea il corpo della richiesta. Formatta il corpo in base a tipo di contenuto multiparte/correlato RFC 2387, che è composto da due parti:
- Metadati. I metadati devono essere inseriti per primi e devono avere un elemento
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. Nella aggiungi due trattini dopo la stringa limite finale.
- Metadati. I metadati devono essere inseriti per primi e devono avere un elemento
Aggiungi queste intestazioni HTTP di primo livello:
Content-Type
. Imposta sumultipart/related
e includi il confine stringa che stai utilizzando per identificare le diverse parti della richiesta. Per esempio:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Impostato 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 alle
metadati.
Durante la creazione dei file, devono specificare un'estensione del file nella sezione name
. Ad esempio, quando crei un file JPEG di foto, potresti specificare
come "name": "photo.jpg"
nei metadati. Le chiamate successive a files.get
restituiscono la proprietà fileExtension
di sola lettura
contenente l'estensione specificata originariamente nel campo name
.
Esegui un caricamento ripristinabile
Un caricamento ripristinabile consente di riprendere un'operazione di caricamento dopo una comunicazione l'errore interrompe il flusso di dati. Poiché non occorre riavviare di file caricati fin dall'inizio, i caricamenti ripristinabili possono anche ridurre la larghezza di banda all'utilizzo 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 (come le attività in background del sistema operativo mobile e alcune richieste di App Engine). Puoi anche utilizzare caricamenti ripristinabili per situazioni in cui vuoi mostrare una barra di avanzamento del caricamento.
Un caricamento ripristinabile consiste in 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 la query parametro diuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Se la richiesta di avvio ha esito positivo, la risposta include un
200 OK
Codice di stato HTTP. 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 di sessione ripristinabile in modo da poter caricare i dati e la query del file lo stato del caricamento. Un URI della 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 del file che vengono trasferiti 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 di di dati di 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 a blocchi. Imposta il 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 stato di caricamento. Un URI della sessione ripristinabile scade dopo una settimana.Copia e salva l'URL della sessione ripristinabile.
Vai a 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 caricati in un'unica richiesta, se non c'è un limite di tempo fisso per ogni singola richiesta richiesta, né occorre visualizzare un indicatore di avanzamento del caricamento. Questo è l'ideale perché richiede meno richieste e migliora delle prestazioni.
Carica i contenuti in più blocchi: utilizza questo approccio se devi ridurre la quantità di dati trasferiti in ogni singola richiesta. Potrebbero servirti per ridurre i dati trasferiti quando esiste un limite di tempo fisso per come nel caso di alcune classi di richieste di App Engine. Questo approccio è utile anche se devi fornire un indicatore personalizzato per che mostra 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 un
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 in multipli di 256 kB (256 x 1024 byte), tranne il blocco finale completato per completare il caricamento. Mantieni la dimensione del chunk più grande possibile in modo che il caricamento sia in modo efficace.
Aggiungi queste intestazioni HTTP:
Content-Length
. Impostato sul numero di byte nel blocco attuale.Content-Range
. Impostalo per mostrare i byte del file che carichi. Per Ad esempio,Content-Range: bytes 0-524287/2000000
mostra che carichi 524.288 byte (256 x 1024 x 2) in un file da 2.000.000 di byte.
Invia la richiesta ed elabora la risposta. Se la richiesta di caricamento è o, se ricevi una risposta
5xx
, segui la procedura Riprendi un caricamento interrotto.Ripeti i passaggi da 1 a 4 per ogni blocco rimanente nel file. Utilizza la
Range
nella risposta per determinare 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, ricevi un 200 OK
o
201 Created
, insieme agli eventuali metadati associati alla risorsa.
Riprendere un caricamento interrotto
Se una richiesta di caricamento viene terminata prima di una risposta o se ricevi una risposta 503
Service Unavailable
, devi riprendere il caricamento interrotto.
HTTP
Per richiedere lo stato del caricamento, crea una richiesta
PUT
vuota al URI della sessione ripristinabile.Aggiungi un'intestazione
Content-Range
per indicare che la posizione attuale file sconosciuto. Ad esempio, impostaContent-Range
su*/2000000
se il tuo la lunghezza totale del file è di 2.000.000 byte. Se non conosci le dimensioni originali impostaContent-Range
su*/*
.Invia la richiesta.
Elabora la risposta:
- Una risposta
200 OK
o201 Created
indica che il caricamento è stato è stata completata 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 IntestazioneRange
della risposta per determinare quali byte hanno ricevuto il server. Se la risposta non ha un'intestazioneRange
o non sono stati ricevuti byte. Ad esempio, un'intestazioneRange
dibytes=0-42
indica che la prima Sono stati ricevuti 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'opzione Intestazione
Content-Range
per indicare la parte del file da inviare. Per Ad esempio,Content-Range: bytes 43-1999999
indica inviare 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
5xx
errori, riprendi o riprova i caricamenti non riusciti a causa della connessione interruzioni. Per saperne di più sulla gestione degli errori5xx
, consulta errori 500, 502, 503, 504. - Per
403 rate limit
errori, riprova a eseguire il caricamento. Per ulteriori informazioni su gestire gli errori403 rate limit
; consulta l'articolo Errore 403:rateLimitExceeded
. - Per eventuali errori
4xx
(tra cui403
) durante un caricamento ripristinabile, riavvia per completare il caricamento. Questi errori indicano che la sessione di caricamento è scaduta e deve essere riavviata richiedendo un nuovo URI sessione. Sessioni di caricamento scadono dopo una settimana di inattività.
Importa in tipi di Documenti Google
Quando crei un file in Drive, potrebbe essere utile convertire il in un tipo di file di Google Workspace, ad esempio Documenti Google o Google. Ad esempio, se vuoi trasformare un documento il tuo elaboratore di testi preferito in Documenti per sfruttare le funzionalità di machine learning.
Per convertire un file in un tipo di file specifico di Google Workspace, specifica la
Google Workspace mimeType
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 comuni
formati di importazione sono:
Da | A |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, testo normale | Documenti Google |
Microsoft Excel, foglio di lavoro OpenDocument, CSV, TSV, testo normale | Fogli Google |
Microsoft PowerPoint, presentazione OpenDocument | 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 contenuti multimediali durante una richiesta update
in una
il file di Documenti, Fogli o Presentazioni,
vengono sostituiti tutti i contenuti
del documento.
Quando converti un'immagine in un documento, Drive utilizza
Riconoscimento ottico dei caratteri (OCR) per convertire l'immagine in testo. Puoi
migliorare la qualità dell'algoritmo OCR specificando il BCP applicabile
47
nel
ocrLanguage
:
. Il testo estratto viene visualizzato nel documento insieme all'immagine incorporata.
Utilizza un ID pregenerato per caricare i file
L'API Drive consente di recuperare un elenco di ID file pregenerati che
e vengono utilizzati per caricare e creare risorse. Le richieste di caricamento e creazione di file possono
utilizza questi ID pregenerati. Imposta il campo id
nei metadati del file.
Per creare ID pregenerati, chiama
files.generateIds
con
di ID da creare.
Puoi riprovare in sicurezza i caricamenti con ID pregenerati, se c'è un'indeterminata
un errore o un timeout del server. Se il file è stato creato correttamente, le successive
nuovi tentativi restituiscono un errore HTTP 409
e non creano file duplicati.
Definisci il testo indicizzabile per i tipi di file sconosciuti
Gli utenti possono utilizzare l'UI di Drive per trovare i contenuti dei documenti. Puoi anche
usa files.list
e fullText
per cercare contenuti della tua app. Per ulteriori informazioni, consulta Ricerca di
file e cartelle.
Drive indicizza automaticamente i documenti per le ricerche
riconosce il tipo di file, inclusi documenti di testo, PDF, immagini con testo e
e altri tipi comuni. Se la tua app salva altri tipi di file (ad esempio disegni,
video e scorciatoie), puoi migliorare la rilevabilità fornendo
testo indicizzabile nel campo contentHints.indexableText
del file.
Per saperne di più sul testo indicizzabile, consulta Gestire i file metadati.