Gérer les métadonnées de fichiers

Ce document aborde des points importants concernant l'attribution de noms aux fichiers et l'utilisation de métadonnées telles que le texte indexable et les vignettes. Pour insérer et récupérer des fichiers, consultez la ressource files.

Spécifier des noms de fichiers et des extensions

Les applications doivent spécifier une extension de fichier dans la propriété de titre lorsqu'elles insèrent des fichiers avec l'API Google Drive. Par exemple, une opération d'insertion d'un fichier JPEG doit spécifier un élément semblable à "name": "cat.jpg" dans les métadonnées.

Les réponses GET suivantes peuvent inclure la propriété fileExtension en lecture seule, renseignée avec l'extension initialement spécifiée dans la propriété name. Lorsqu'un utilisateur Google Drive demande à télécharger un fichier ou que le fichier est téléchargé via le client de synchronisation, Drive crée un nom de fichier complet (avec une extension) basé sur le titre. Si l'extension est manquante, Drive tente de déterminer l'extension en fonction du type MIME du fichier.

Enregistrer le texte indexable

Drive indexe automatiquement les documents pour la recherche lorsqu'il reconnaît le type de fichier, y compris les documents texte, les PDF, les images contenant du texte et d'autres types courants. Si votre application enregistre d'autres types de fichiers (tels que des dessins, des vidéos et des raccourcis), vous pouvez améliorer la visibilité en fournissant du texte indexable dans le champ contentHints.indexableText du fichier.

Le texte indexable est indexé au format HTML. Si vous enregistrez la chaîne de texte indexable <section attribute="value1">Here's some text</section>, "Voici du texte" est indexé, mais pas "valeur1". Pour cette raison, l'enregistrement du code XML en tant que texte indexable n'est pas aussi utile que l'enregistrement du code HTML.

Lorsque vous spécifiez indexableText, gardez également à l'esprit les points suivants:

  • La taille de contentHints.indexableText ne doit pas dépasser 128 Ko.
  • Identifiez les termes et concepts clés que les utilisateurs doivent rechercher.
  • N'essayez pas de trier le texte par ordre d'importance, car l'indexeur le fait efficacement pour vous.
  • Votre application doit mettre à jour le texte indexable à chaque enregistrement.
  • Assurez-vous que le texte est en rapport avec le contenu ou les métadonnées du fichier.

Ce dernier point peut sembler évident, mais il est important. Il est déconseillé d'ajouter des termes fréquemment recherchés pour forcer l'affichage d'un fichier dans les résultats de recherche. Cela peut frustrer les utilisateurs et même les motiver à supprimer le fichier.

Importer des vignettes

Drive génère automatiquement des vignettes pour de nombreux types de fichiers courants, tels que Google Docs, Sheets et Slides. Les vignettes aident l'utilisateur à mieux identifier les fichiers Drive.

Pour les types de fichiers pour lesquels Drive ne peut pas générer de vignette standard, vous pouvez fournir une vignette générée par votre application. Lors de la création ou de la mise à jour du fichier, importez une vignette en définissant le champ contentHints.thumbnail sur la ressource files.

Notamment :

  • Définissez le champ contentHints.thumbnail.image sur l'image encodée en base64 sécurisée pour l'URL et le nom de fichier (consultez la section 5 du document RFC 4648).
  • Définissez le champ contentHints.thumbnail.mimeType sur le type MIME approprié pour la vignette.

Si Drive peut générer une vignette à partir du fichier, il utilise celle générée automatiquement et ignore toutes les vignettes que vous avez peut-être importées. S'il ne peut pas générer de vignette, il utilise celle que vous fournissez.

Les miniatures doivent respecter les règles suivantes:

  • Elles peuvent être importées aux formats PNG, GIF ou JPG.
  • La largeur recommandée est de 1 600 pixels.
  • La largeur minimale est de 220 pixels.
  • La taille maximale des fichiers est de 2 Mo.
  • Elles doivent être mises à jour par votre application à chaque enregistrement.

Pour en savoir plus, consultez la ressource files.

Récupérer des vignettes

Vous pouvez récupérer les métadonnées des fichiers Drive, y compris les vignettes. Les informations sur les vignettes sont hébergées dans le champ thumbnailLink de la ressource files.

Afficher une vignette spécifique

L'exemple de code suivant montre une requête de méthode files.get avec plusieurs champs en tant que paramètre de requête pour renvoyer les métadonnées thumbnailLink pour un fichier spécifique. Pour en savoir plus, consultez la section Renvoyer des champs spécifiques pour un fichier.

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

Remplacez FILE_ID par le nom (fileId) du fichier que vous souhaitez rechercher.

Le cas échéant, la requête renvoie une URL éphémère vers la vignette du fichier. En règle générale, le lien reste actif pendant plusieurs heures. Le champ n'est renseigné que lorsque l'application à l'origine de la demande peut accéder au contenu du fichier. Si le fichier n'est pas partagé publiquement, l'URL renvoyée dans thumbnailLink doit être récupérée à l'aide d'une requête avec identifiants.

Afficher une liste de vignettes

L'exemple de code suivant montre une requête de méthode files.list avec plusieurs champs en tant que paramètre de requête pour renvoyer les métadonnées thumbnailLink pour une liste de fichiers. Pour en savoir plus, consultez la section Rechercher des fichiers et des dossiers.

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

Pour limiter les résultats de recherche à un type de fichier spécifique, appliquez une chaîne de requête pour définir le type MIME. L'exemple de code suivant montre comment limiter la liste aux fichiers Google Sheets. Pour en savoir plus sur les types MIME, consultez la section Types MIME compatibles avec Google Workspace et Google Drive.

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