Guida al confronto tra API Drive v2 e v3

L'ultima versione dell'API Google Drive è la v3. Le prestazioni nella versione 3 sono migliori perché le ricerche restituiscono solo un sottoinsieme di campi. Utilizza la versione corrente, a meno che tu non abbia bisogno della raccolta v2. Se utilizzi la v2, valuta la possibilità di eseguire la migrazione alla v3. Per eseguire la migrazione, vedi Eseguire la migrazione all'API Drive v3. Per un elenco completo delle differenze nelle versioni, consulta la documentazione di riferimento per il confronto tra API Drive v2 e v3.

Se vuoi continuare a utilizzare la versione 2, consulta l'emendamento Guida all'API Drive v2 per sapere come devono essere modificate alcune istruzioni della versione 3 per gli sviluppatori della versione 2.

Per ulteriori informazioni sui miglioramenti dell'API Drive v3, puoi guardare il seguente video degli ingegneri di Google che parlano della nuova progettazione dell'API.

Miglioramenti V3

Per ottimizzare le prestazioni e ridurre la complessità del comportamento delle API, la versione v3 fornisce questi miglioramenti rispetto alla versione precedente dell'API:

  • Le ricerche di file e Drive condivisi non restituiscono risorse complete per impostazione predefinita, ma viene restituito solo un sottoinsieme dei campi di uso comune. Per ulteriori dettagli su fields, consulta i metodi files.list e drives.list.
  • Quasi tutti i metodi che restituiscono una risposta ora richiedono il parametro fields. Per un elenco di tutti i metodi che richiedono fields, consulta la documentazione di riferimento dell'API Drive.
  • Le risorse con funzionalità duplicate sono state rimosse. Ecco alcuni esempi:
    • Il metodo files.list svolge la stessa funzionalità delle raccolte Children e Parents, quindi vengono rimossi dalla versione 3.
    • I metodi Realtime.* sono stati rimossi.
  • I dati delle app non vengono restituiti per impostazione predefinita nelle ricerche. Nella versione v2, puoi impostare l'ambito drive.appdata, che restituisce i dati dell'applicazione dal metodo files.list e dal metodo changes.list, ma rallenta le prestazioni. Nella versione 3 puoi impostare l'ambito drive.appdata e anche il parametro di query spaces=appDataFolder per richiedere i dati dell'applicazione.
  • Tutte le operazioni di aggiornamento utilizzano PATCH anziché PUT.
  • Per esportare i documenti Google, utilizza il metodo files.export.
  • Il comportamento del metodo changes.list è diverso. Anziché usare gli ID delle modifiche, usa token di pagina opachi. Per eseguire il polling della raccolta delle modifiche, chiama prima il metodo changes.getStartPageToken per ottenere il valore iniziale. Per le query successive, il metodo changes.list restituisce il valore newStartPageToken.
  • I metodi di aggiornamento ora rifiutano le richieste che specificano campi non scrivibili.
  • I campi v2 exportFormats e importFormats nella risorsa about sono elenchi di formati di importazione o esportazione consentiti. Nella versione 3, sono mappe di tipo MIME di possibili destinazioni per tutte le importazioni o esportazioni supportate.
  • Gli alias v2 appdata e appfolder sono ora appDataFolder nella v3.
  • La risorsa properties è stata rimossa dalla versione 3. La risorsa files ha il campo properties che contiene coppie chiave-valore vere. Il campo properties contiene proprietà pubbliche, mentre il campo appProperties contiene proprietà private, quindi il campo della visibilità non è necessario.
  • Il campo modifiedTime nella risorsa files si aggiorna l'ultima volta che un utente ha modificato il file. Nella versione 2, il campo modifiedDate era modificabile all'aggiornamento solo se avevi impostato il campo setModifiedDate.
  • Il campo viewedByMeTime nella risorsa files non si aggiorna automaticamente.
  • Per importare formati di Documenti Google, imposta il target mimeType appropriato nel corpo della risorsa. Nella versione 2, hai impostato ?convert=true.
  • Le operazioni di importazione restituiscono un errore 400 se il formato non è supportato.
  • I lettori e i commentatori non possono visualizzare le autorizzazioni.
  • L'alias me per le autorizzazioni è stato rimosso.
  • Alcune funzionalità erano disponibili come parte della risorsa di richiesta, ma sono invece disponibili come parametro di richiesta. Ad esempio:
    • Nella versione v2, puoi utilizzare children.delete per rimuovere un file secondario da una cartella principale.
    • Nella versione 3, utilizzi files.update nell'elemento secondario con ?removeParents=parent_id nell'URL.

Altre differenze

I nomi dei parametri e dei campi sono diversi nella versione 3. Ecco alcuni esempi:

  • La proprietà name sostituisce title nella risorsa files.
  • Time è il suffisso per tutti i campi relativi a data e ora anziché Date.
  • Le operazioni di elenco non utilizzano il campo items per contenere il set di risultati. Il tipo di risorsa fornisce un campo per i risultati (ad esempio files o changes).