Gestire i metadati dei file

Questo documento tratta considerazioni importanti per la denominazione dei file e l'utilizzo di metadati come testo indicizzabile e miniature. Per inserire e recuperare i file, consulta la risorsa files.

Specificare nomi ed estensioni dei file

Quando inseriscono file con l'API Google Drive, le app devono specificare un'estensione del file nella proprietà title. Ad esempio, un'operazione per inserire un file JPEG deve specificare qualcosa come "name": "cat.jpg" nei metadati.

Le risposte GET successive possono includere la proprietà fileExtension di sola lettura compilata con l'estensione specificata originariamente 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 è presente, Drive tenta di determinarla in base al tipo MIME del file.

Salvare il testo indicizzabile

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 (come disegni, video e scorciatoie), puoi migliorare la rilevabilità fornendo testo indicizzabile nel campo contentHints.indexableText del file.

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

Quando specifichi indexableText, tieni presente anche quanto segue:

  • Il limite di dimensioni per contentHints.indexableText è 128 KB.
  • Acquisire i termini e i concetti chiave che prevedi che un utente cerchi.
  • Non tentare di ordinare il testo in base all'importanza perché l'indicizzatore lo fa in modo efficiente per te.
  • La tua applicazione deve aggiornare il testo indicizzabile 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ò frustrare 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 cui Drive non può generare una miniatura standard, puoi fornire un'immagine della 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 codificata in base64 sicura per URL e nomi file (vedi RFC 4648 sezione 5).
  • 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 le seguenti regole:

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

Per ulteriori informazioni, consulta la risorsa files.

Recuperare le miniature

Puoi recuperare i metadati, incluse le miniature, dei file di Drive. Le informazioni sulle miniature si trovano 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, vedi 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.

Restituisce 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 Fogli Google. Per ulteriori informazioni sui tipi MIME, vedi Tipi MIME supportati da 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)