Gestire i metadati dei file

Questo documento illustra 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.

Panoramica dei metadati

Nell'API Google Drive, la risorsa files rappresenta i metadati. A differenza delle API in cui i metadati sono un sotto-oggetto, l'API Drive considera l'intera risorsa files come metadati. Puoi accedere ai metadati direttamente tramite i metodi get o list nella risorsa files.

Per impostazione predefinita, i metodi get e list restituiscono solo un insieme parziale di campi. Per recuperare dati specifici, devi definire il fields parametro di sistema nella richiesta. Se omesso, il server restituisce un sottoinsieme predefinito di campi specifici per il metodo. Ad esempio, il metodo list restituisce solo i campi kind, id, name, mimeType e resourceKey per ogni file. Per restituire campi diversi, vedi Restituire campi specifici.

Inoltre, la visibilità dei metadati dipende dal ruolo dell'utente nel file. La risorsa permissions non determina le azioni consentite di un utente su un file o una cartella. La risorsa files contiene invece una raccolta di campi capabilities booleani. L'API Google Drive deriva questi capabilities dalla risorsa permissions associata al file o alla cartella. Per saperne di più, vedi Informazioni sulle funzionalità dei file.

L'API Drive offre due ambiti di metadati limitati: drive.metadata e drive.metadata.readonly. L'ambito drive.metadata consente di visualizzare e gestire i metadati dei file, mentre drive.metadata.readonly è di sola lettura. Entrambe vietano rigorosamente l'accesso ai contenuti dei file. Per saperne di più, vedi Scegliere gli ambiti dell'API Google Drive.

Infine, verifica sempre la logica relativa alle autorizzazioni e agli ambiti. Ad esempio, un utente potrebbe essere proprietario di un file con autorizzazioni complete, ma l'API Drive bloccherà i tentativi di modifica o download del file se la tua app ha solo l'ambito drive.metadata.readonly.

Specificare nomi ed estensioni dei file

Le app devono specificare un'estensione file nella proprietà name) quando inseriscono file con l'API Google Drive. 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à di sola lettura fileExtension 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 nome. 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 dimensione per contentHints.indexableText è 128 KB.
  • Acquisire i termini e i concetti chiave che prevedi che un utente possa cercare.
  • 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 motivarli 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 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 la sezione 5 dell'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 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 dalla tua applicazione a ogni salvataggio.

Per saperne di più, 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 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 temporaneo alla miniatura del file. In genere, il link è valido per 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 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, consulta 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)