Gestire i metadati dei file

Questo documento contiene considerazioni importanti per l'assegnazione di un nome ai file e l'uso di metadati come testo indicizzabile e miniature. Per inserire e recuperare file, consulta la risorsa files.

Specificare nomi ed estensioni dei file

Le app devono specificare un'estensione del file nella proprietà del titolo durante l'inserimento di file con l'API Google Drive. Ad esempio, un'operazione per inserire un file JPEG dovrebbe specificare qualcosa come "name": "cat.jpg" nei metadati.

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

Salva testo indicizzabile

Nota: a partire dal 31 ottobre 2022, il testo indicizzabile potrà essere mostrato negli snippet dei risultati e questo influirà sui risultati di ricerca in più posizioni, tra cui Cloud Search e l'overlay di ricerca su Drive e Gmail.

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

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

Quando specifichi indexableText, tieni presente anche:

• Il limite per le dimensioni di contentHints.indexableText è 128 kB.
• Annota i termini e i concetti chiave che ti aspetti vengano cercati da un utente.
• Non cercare di ordinare il testo in ordine di importanza perché l'indicizzatore lo fa in modo efficiente per te.
• L'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 può sembrare ovvio, ma è importante. Non è consigliabile aggiungere termini di ricerca comuni per forzare la visualizzazione di un file nei risultati di ricerca. Questo può scoraggiare gli utenti e persino spingerli a eliminare il file.

Carica miniature

Drive genera automaticamente miniature per molti tipi di file comuni, come Documenti, Fogli e Presentazioni. 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 dall'applicazione. Durante la creazione o l'aggiornamento del file, carica una miniatura impostando il campo contentHints.thumbnail sulla 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 RFC 4648).
• Imposta il campo contentHints.thumbnail.mimeType sul tipo MIME appropriato per la miniatura.

Se Drive è in grado di generare una miniatura dal file, utilizza quella generata automaticamente e ignora qualsiasi tu abbia caricato. Se non può generare una miniatura, utilizza quella che hai fornito.

Le miniature devono rispettare le seguenti regole:

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

Importante: le miniature vengono invalidate ogni volta che vengono modificati i contenuti del file. Quando fornisci le miniature, è importante caricare nuove miniature ogni volta che vengono modificati i contenuti. Le modifiche ai metadati non invalidano le miniature.

Per ulteriori informazioni, consulta la risorsa files.

Recupera le miniature

Puoi recuperare i metadati, incluse le miniature, per i 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 ricerca 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 valore 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 viene 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 ricerca per restituire i metadati thumbnailLink per un elenco di file. Per ulteriori informazioni, consulta Ricerca di file e cartelle.

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

Per limitare i risultati della 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 la pagina relativa ai 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)