Creare e gestire i file

Questa guida spiega come creare e gestire i file in Google Drive utilizzando l'API Google Drive.

Crea file

Per creare un file in Drive che contenga contenuti (media), devi caricare i dati del file. Puoi caricare i metadati e i contenuti di un file insieme in un'unica richiesta (caricamento in più parti) o caricare solo i contenuti multimediali (caricamento semplice). Per ulteriori informazioni, vedi Caricare i dati dei file.

Per creare un file che non contenga metadati o contenuti, utilizza il create metodo sulla files risorsa senza parametri.

Quando crei il file, il metodo restituisce una risorsa files. Al file viene assegnato un kind di drive.file, un id, un name di "Untitled" e un mimeType di application/octet-stream. uploadType è contrassegnato come obbligatorio, ma il valore predefinito è media, quindi non devi fornirlo.

Per ulteriori informazioni sui limiti dei file di Drive, vedi Limiti di file e cartelle.

I seguenti esempi di codice mostrano come creare un file senza metadati o contenuti:

/**
 * Create an empty file.
 * @return {string} The created file's ID.
 */
async function createEmptyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.create({});
    console.log('File ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl -X POST 'https://www.googleapis.com/drive/v3/files' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Utilizzare il parametro fields

Se vuoi specificare i campi da restituire nella risposta, puoi impostare il fields parametro di sistema con qualsiasi metodo della ris3/} risorsa.files Se ometti il parametro fields, il server restituisce un insieme predefinito di campi specifici per il metodo. Ad esempio, il list metodo restituisce solo i campi kind, id, name, mimeType e resourceKey per ogni file. Per restituire campi diversi, vedi Restituire campi specifici.

Proprietà del file

Quando un file viene creato utilizzando l'API Drive, la proprietà dipende dalle credenziali di autenticazione utilizzate dall'app nei seguenti modi:

• Account utente (OAuth 2.0): se l'applicazione esegue l'autenticazione per conto di un utente, quest'ultimo diventa il proprietario del file. Il file risiede nella cartella Il mio Drive o in una specificata cartella. Consuma la quota di spazio di archiviazione.

• Account di servizio: se l'applicazione esegue l'autenticazione utilizzando un account di servizio, quest'ultimo è il proprietario del file. Il file risiede nello spazio di archiviazione Drive dedicato dell'account di servizio. I file non vengono visualizzati in altri account di spazio di archiviazione di Drive, a meno che non siano condivisi esplicitamente. Se l'account di servizio viene eliminato, tutti i file di sua proprietà vengono eliminati immediatamente.

  Se utilizzi un account di servizio, ma vuoi che un account utente specifico sia proprietario di un file, utilizza la delega a livello di dominio. In questo modo, l'account di servizio può impersonare un utente e creare file per suo conto. Per ulteriori informazioni, vedi Delegare l'autorità a livello di dominio all'account di servizio .

Per ulteriori informazioni sulle autorizzazioni dei file, vedi Condividere file, cartelle e Drive.

Generare ID da utilizzare con i file

Il metodo generateIds sulla risorsa files consente di pregenerare ID file univoci che possono essere utilizzati durante la creazione o la copia di file e cartelle in Drive. Questa operazione può essere utile quando devi controllare gli ID file dalla tua app, anziché lasciare che Drive li assegni automaticamente.

Puoi impostare il numero di ID generati utilizzando il count parametro di query. Se count non è impostato, per impostazione predefinita vengono restituiti 10 ID. Il numero massimo di ID che puoi richiedere è limitato a 1000.

Puoi anche designare lo space in cui è possibile utilizzare gli ID e il type di elementi per cui è possibile utilizzare gli ID.

Una volta generato un ID, può essere passato al metodo create o copy tramite il campo id. In questo modo, il file creato o copiato utilizza l'ID predeterminato.

Se il file viene creato o copiato correttamente, i tentativi successivi restituiscono un codice di stato HTTP 409 Conflict e non vengono creati file duplicati.

Tieni presente che gli ID pregenerati non sono supportati per la creazione di file di Google Workspace, ad eccezione dei tipi application/vnd.google-apps.drive-sdk e application/vnd.google-apps.folder MIME. Allo stesso modo, i caricamenti che fanno riferimento a una conversione in un formato di file di Google Workspace non sono supportati.

I seguenti esempi di codice mostrano come pregenerare ID file univoci:

/**
 * Pre-generate unique file IDs.
 */
async function generateFileIds() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.generateIds({
      count: 10,
      space: 'drive'
    });
    const ids = response.data.ids;
    console.log('Generated IDs:');
    for (const id of ids) {
      console.log(id);
    }
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl 'https://www.googleapis.com/drive/v3/files/generateIds?count=10&space=drive' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Creare file solo con metadati

I file solo con metadati non contengono contenuti. I metadati sono dati (come name, mimeType e createdTime) che descrivono il file. I campi come name sono indipendenti dall'utente e vengono visualizzati allo stesso modo per ogni utente, mentre i campi come viewedByMeTime contengono valori specifici dell'utente.

Un esempio di file solo con metadati è una cartella con il tipo MIME application/vnd.google-apps.folder. Per ulteriori informazioni, vedi Creare e popolare le cartelle. Un altro esempio è una scorciatoia che rimanda a un altro file su Drive con il tipo MIME application/vnd.google-apps.shortcut. Per ulteriori informazioni, vedi Creare una scorciatoia a un file di Drive.

Gestire le immagini in miniatura

Le miniature aiutano gli utenti a identificare i file di Drive. Drive può generare automaticamente miniature per i tipi di file comuni oppure puoi fornire un' immagine in miniatura generata dalla tua app. Per ulteriori informazioni, vedi Caricare le miniature.

Copiare un file esistente

Per copiare un file e applicare gli aggiornamenti richiesti, utilizza il copy metodo sulla risorsa files. Per trovare il fileId da copiare, utilizza il list metodo.

Puoi applicare gli aggiornamenti tramite la semantica delle patch, il che significa che puoi apportare modifiche parziali a una risorsa. Devi impostare esplicitamente i campi che intendi modificare nella richiesta. I campi non inclusi nella richiesta mantengono i valori esistenti. Per ulteriori informazioni, vedi Utilizzare le risorse parziali.

Puoi preimpostare l'ID file del file copiato utilizzando il generateIds metodo. Per ulteriori informazioni, vedi Generare ID da utilizzare con i file.

Tieni presente che devi utilizzare un ambito API Drive appropriato per autorizzare la chiamata. Per ulteriori informazioni sugli ambiti di Drive, vedi Scegliere gli ambiti dell'API Google Drive.

I seguenti esempi di codice mostrano come copiare un file e aggiornarne il nome:

/**
 * Copy an existing file.
 * @return {string} The copied file's ID.
 */
async function copyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.copy({
      fileId: 'FILE_ID',
      requestBody: {
        name: 'FILE_COPY_NAME'
      }
    });
    console.log('Copied file ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/copy' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "name": "FILE_COPY_NAME"
 }'

Copia commenti

Per copiare commenti e suggerimenti quando copi un file di Documenti, Fogli o Presentazioni Google, imposta il copyComments parametro di query su true. Drive copia solo i commenti aperti (commenti non risolti). Per altri tipi di file, Drive ignora questo parametro.

Per ulteriori informazioni su autorizzazioni, attribuzione dei commenti e considerazioni sull'accesso , vedi Limiti e considerazioni.

Limiti e considerazioni

Quando ti prepari a copiare i file, tieni presente questi limiti e considerazioni:

• Autorizzazioni:

  • L'DownloadRestrictionsMetadata oggetto della risorsa files determina chi può copiare il file. Per ulteriori informazioni, vedi Impedire agli utenti di scaricare, stampare o copiare un file.
  • La risorsa campo capabilities.canCopy determina se l'utente può copiare un file. Per ulteriori informazioni, vedi Informazioni sulle funzionalità dei file.
  • Per copiare i commenti, devi avere l'autorizzazione per leggerli nel file di origine. Se non hai l'autorizzazione per leggere i commenti e imposti copyComments su true, l'operazione di copia viene eseguita correttamente, ma i commenti non vengono copiati.
  • La copia dei commenti non concede agli autori dei commenti originali l'accesso al nuovo file. Gli elenchi di controllo dell'accesso (ACL) del nuovo file sono indipendenti dagli ACL del file di origine.
  • L'utente che ha creato la copia è il proprietario del file copiato. Non vengono replicate altre impostazioni di condivisione dal file di origine. Se la copia viene creata in una cartella condivisa, eredita le autorizzazioni di quella cartella.
  • La proprietà di un file copiato potrebbe cambiare e la copia potrebbe non ereditare le impostazioni di condivisione del file originale. Queste impostazioni potrebbero dover essere reimpostate.

• Gestione dei file:

  • Alcuni file, come le scorciatoie di terze parti, non possono mai essere copiati.
  • Puoi copiare un file solo in una cartella principale. La specifica di più genitori non è supportata. Se il parents campo non è specificato, il file eredita tutti i genitori rilevabili dal file di origine.
  • Anche se una cartella è un tipo di file, non puoi copiarla. Crea invece una cartella di destinazione e imposta il campo parents dei file esistenti sulla cartella di destinazione. A questo punto puoi eliminare la cartella di origine originale.
  • A meno che non venga specificato un nuovo nome file, il metodo copy produce un file con lo stesso nome dell'originale.
  • L'utilizzo eccessivo di copy può comportare il superamento dei limiti di quota dell'API Drive. Per ulteriori informazioni, vedi Limiti di utilizzo.

Argomenti correlati

Ecco alcuni passaggi successivi che potresti provare:

• Per caricare i dati dei file quando crei o aggiorni un file, vedi Caricare i dati dei file.

• Per creare un file in una cartella specifica, vedi Creare un file in una cartella specifica.

• Per spostare i file, vedi Spostare i file tra le cartelle.

• Per lavorare con i metadati dei file, vedi Gestire i metadati dei file.

• Per eliminare un file, vedi Spostare file e cartelle nel cestino o eliminarli.