Gestire i metadati dei file

Questo documento illustra considerazioni importanti per assegnare i nomi ai file e lavorare con i metadati, come testo indicizzato e miniature. Per inserire e recuperare i file, consulta la risorsa files.

Specifica i nomi e le estensioni dei file

Le app devono specificare un'estensione del file nella proprietà title quando inseriscono i file con l'API Google Drive. Ad esempio, un'operazione per inserire un file JPEG deve specificare qualcosa di simile a "name": "cat.jpg" nei metadati.

Le risposte GET successive possono includere la proprietà fileExtension di sola lettura compilata con l'estensione originariamente specificata nella proprietà name. Quando un utente di Google Drive richiede di scaricare un file o quando il file viene scaricato tramite il client di sincronizzazione, Drive crea un nome file completo (con estensione) in base al titolo. Nei casi in cui l'estensione non sia presente, Drive tenta di determinare l'estensione in base al tipo MIME del file.

Salvare il testo indicizzato

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 la tua app salva altri tipi di file (ad esempio disegni, video e scorciatoie), puoi migliorare la rilevabilità fornendo testo indicizzato nel campo contentHints.indexableText del file.

Il testo indicizzato viene indicizzato come HTML. Se salvi la stringa di testo indicizzabile<section attribute="value1">Here's some text</section>, "Ecco del testo" viene indicizzato, ma non "valore1". Per questo motivo, salvare il file XML come testo indicizzato non è utile quanto salvare il file HTML.

Quando specifichi indexableText, tieni presente anche quanto segue:

  • Il limite per le dimensioni di contentHints.indexableText è 128 kB.
  • Acquisisci i termini e i concetti chiave che prevedi che un utente cerchi.
  • Non provare a ordinare il testo in ordine di importanza perché lo fa l'indicizzatore in modo efficiente.
  • L'applicazione deve aggiornare il testo indicizzato a ogni salvataggio.
  • Assicurati che il testo sia correlato ai contenuti o ai metadati del file.

Quest'ultimo punto potrebbe sembrare ovvio, ma è importante. Non è una buona idea aggiungere termini di ricerca comuni per forzare la visualizzazione di un file nei risultati di ricerca. Ciò può scoraggiare gli utenti e persino spingerli a eliminare il file.

Caricare miniature

Drive genera automaticamente miniature per molti tipi di file comuni, come Documenti, Fogli e Presentazioni Google. Le miniature aiutano l'utente a identificare meglio i file di Drive.

Per i tipi di file per i quali Drive non può generare una miniatura standard, puoi fornire un'immagine in miniatura generata dalla tua applicazione. Durante la creazione o l'aggiornamento del file, carica una miniatura impostando il campo contentHints.thumbnail nella risorsa files.

In particolare:

  • Imposta il campo contentHints.thumbnail.image sull'immagine con codifica base64 sicura per URL e nome file (consulta la sezione 5 della RFC 4648).
  • Imposta il campo contentHints.thumbnail.mimeType sul tipo MIME appropriato per la miniatura.

Se Drive può generare una miniatura dal file, utilizza quella generata automaticamente e ignora quelle che potresti aver caricato. Se non riesce a generare una miniatura, utilizza quella che fornisci.

Le miniature devono rispettare queste regole:

  • Possono essere caricate in formato PNG, GIF o JPG.
  • La larghezza consigliata è di 1600 pixel.
  • La larghezza minima è 220 pixel.
  • La dimensione massima del file è 2 MB.
  • Dovrebbero essere aggiornati dall'applicazione a ogni salvataggio.

Per ulteriori informazioni, consulta la risorsa files.

Recuperare le miniature

Puoi recuperare i metadati, incluse le miniature, per i file di Drive. Le informazioni sulle miniature sono contenute nel campo thumbnailLink della risorsa files.

Restituire una miniatura specifica

Il seguente esempio di codice mostra una richiesta del metodo files.get con più campi come parametro di query per restituire i metadati thumbnailLink per un file specifico. Per ulteriori informazioni, consulta Restituire campi specifici per un file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Sostituisci FILE_ID con il fileId del file che vuoi trovare.

Se disponibile, la richiesta restituisce un URL di breve durata alla miniatura del file. In genere, il link dura diverse ore. Il campo viene compilato solo quando l'app richiedente può accedere ai contenuti del file. Se il file non è condiviso pubblicamente, l'URL restituito in thumbnailLink deve essere recuperato utilizzando una richiesta con credenziali.

Restituire un elenco di miniature

Il seguente esempio di codice mostra una richiesta del metodo files.list con più campi come parametro di query per restituire i metadati thumbnailLink per un elenco di file. Per ulteriori informazioni, vedi Cercare file e cartelle.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Per limitare i risultati di ricerca a un tipo di file specifico, applica una stringa di query per impostare il tipo MIME. Ad esempio, il seguente esempio di codice mostra come limitare l'elenco ai file di Fogli Google. Per saperne di più sui tipi MIME, consulta l'articolo Tipi MIME supportati per Google Workspace e Google Drive.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)