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 files risorsa.

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 tratta l'intera risorsa files come metadati. Puoi accedere ai metadati direttamente tramite i get o list metodi sulla files risorsa.

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, consulta 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 booleani capabilities. L'API Google Drive deriva queste capabilities dalla risorsa permissions associata al file o alla cartella. Per saperne di più, consulta 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. Entrambi vietano rigorosamente l'accesso ai contenuti dei file. Per saperne di più, consulta Scegliere gli ambiti di API Google Drive.

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

Specificare nomi ed estensioni dei file

Quando inseriscono file con l'API Google Drive, le app devono specificare un'estensione di file nella name) proprietà. 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 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 (ad esempio disegni, video e scorciatoie), puoi migliorare la rilevabilità fornendo testo indicizzabile nel contentHints.indexableText campo 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 "Here's some text", 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 è di 128 KB.
  • Acquisisci i termini e i concetti chiave che prevedi che un utente cerchi.
  • Non provare a ordinare il testo in base all'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 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. Questo può frustrare gli utenti e persino motivarli a eliminare il file.

Caricare le miniature

Drive genera automaticamente le 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 miniatura generata dalla tua applicazione. Durante la creazione o l'aggiornamento del file, carica una miniatura impostando il contentHints.thumbnail campo sulla files risorsa.

In particolare:

  • Imposta il campo contentHints.thumbnail.image sull'immagine codificata in base64 sicura per URL e nomi file (vedi la sezione 5 di 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 è di 220 pixel.
  • La dimensione massima del file è di 2 MB.
  • Devono essere aggiornate dalla tua applicazione a ogni salvataggio.

Per saperne di più, consulta la files risorsa.

Recuperare le miniature

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

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 saperne di più, 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 list con più campi come parametro di query per restituire i metadata thumbnailLink per un elenco di file. Per saperne di più, consulta 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 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)