Ce document aborde des points importants à prendre en compte pour nommer des fichiers et utiliser des métadonnées telles que du texte indexable et des miniatures. Pour insérer et récupérer des fichiers, consultez la ressource files.
Présentation des métadonnées
Dans l'API Google Drive, la ressource files représente les métadonnées. Contrairement aux API où les métadonnées sont un sous-objet, l'API Drive traite l'intégralité de la ressource files comme des métadonnées. Vous pouvez accéder directement aux métadonnées à l'aide des méthodes get ou list sur la ressource files.
Par défaut, les méthodes get et list ne renvoient qu'un ensemble partiel de champs. Pour récupérer des données spécifiques, vous devez définir le paramètre système fields dans votre demande. Si ce paramètre est omis, le serveur renvoie un sous-ensemble de champs par défaut spécifique à la méthode. Par exemple, la méthode list ne renvoie que les champs kind, id, name, mimeType et resourceKey pour chaque fichier. Pour renvoyer différents champs, consultez Renvoyer des champs spécifiques.
De plus, la visibilité des métadonnées dépend du rôle de l'utilisateur sur le fichier. La ressource permissions ne détermine pas les actions autorisées d'un utilisateur sur un fichier ou un dossier. Au lieu de cela, la ressource files contient une collection de champs booléens capabilities. L'API Google Drive dérive ces capabilities de la ressource permissions associée au fichier ou au dossier. Pour en savoir plus, consultez Comprendre les fonctionnalités des fichiers.
L'API Drive propose deux habilitations de métadonnées restreintes : drive.metadata et drive.metadata.readonly. Le champ d'application drive.metadata vous permet d'afficher et de gérer les métadonnées des fichiers, tandis que drive.metadata.readonly est en lecture seule. Les deux interdisent strictement l'accès au contenu des fichiers. Pour en savoir plus, consultez Choisir les habilitations de l'API Google Drive.
Enfin, vérifiez toujours votre logique concernant les autorisations et les niveaux d'accès. Par exemple, un utilisateur peut être propriétaire d'un fichier avec des autorisations complètes, mais l'API Drive bloquera les tentatives de modification ou de téléchargement du fichier si votre application ne dispose que du champ d'application drive.metadata.readonly.
Spécifier les noms et les extensions de fichiers
Les applications doivent spécifier une extension de fichier dans la propriété name) lors de l'insertion de fichiers avec l'API Google Drive. Par exemple, une opération d'insertion d'un fichier JPEG doit spécifier quelque chose comme "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 lorsque le fichier est téléchargé via le client de synchronisation, Drive crée un nom de fichier complet (avec l'extension) en fonction du nom. Si l'extension est manquante, Drive tente de la déterminer en fonction du type MIME du fichier.
Enregistrer du 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 avec 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 détectabilité 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 "value1". Par conséquent, enregistrer du code XML en tant que texte indexable n'est pas aussi utile que d'enregistrer du code HTML.
Lorsque vous spécifiez indexableText, gardez également à l'esprit les points suivants :
- La taille limite pour
contentHints.indexableTextest de 128 Ko. - Identifiez les termes et concepts clés que les utilisateurs sont susceptibles de 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 lié au contenu ou aux métadonnées du fichier.
Ce dernier point peut sembler évident, mais il est important. Il n'est pas judicieux d'ajouter des termes de recherche courants pour forcer l'affichage d'un fichier dans les résultats de recherche. Cela peut frustrer les utilisateurs et même les inciter à supprimer le fichier.
Importer des miniatures
Drive génère automatiquement des miniatures pour de nombreux types de fichiers courants, tels que Google Docs, Sheets et Slides. Les miniatures 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 image de vignette générée par votre application. Lors de la création ou de la mise à jour d'un fichier, importez une miniature en définissant le champ contentHints.thumbnail sur la ressource files.
Plus spécifiquement :
- Définissez le champ
contentHints.thumbnail.imagesur l'image encodée en base64 sécurisée pour les URL et les noms de fichiers (voir la section 5 de la norme RFC 4648). - Définissez le champ
contentHints.thumbnail.mimeTypesur le type MIME approprié pour la miniature.
Si Drive peut générer une miniature à partir du fichier, il utilise celle générée automatiquement et ignore celles 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 :
- Vous pouvez l'importer 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.
- Votre application doit les mettre à jour à chaque enregistrement.
Pour en savoir plus, consultez la ressource files.
Récupérer des miniatures
Vous pouvez récupérer les métadonnées, y compris les miniatures, des fichiers Drive.
Les informations sur les miniatures sont stockées dans le champ thumbnailLink de la ressource files.
Renvoyer une miniature spécifique
L'exemple de code suivant montre une requête de méthode get avec plusieurs champs en tant que paramètre de requête pour renvoyer les métadonnées thumbnailLink d'un fichier spécifique. Pour en savoir plus, consultez 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 fileId du fichier que vous souhaitez trouver.
Si elle est disponible, la requête renvoie une URL éphémère vers la miniature du fichier.
En général, le lien est valable plusieurs heures. Ce champ n'est renseigné que lorsque l'application qui envoie 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.
Renvoyer une liste de miniatures
L'exemple de code suivant montre une requête de méthode list avec plusieurs champs en tant que paramètre de requête pour renvoyer les métadonnées thumbnailLink d'une liste de fichiers. Pour en savoir plus, consultez 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. Par exemple, l'exemple de code suivant montre comment limiter la liste aux fichiers Google Sheets. Pour en savoir plus sur les types MIME, consultez 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)