Ajouter des propriétés de fichier personnalisées

Les propriétés de fichier personnalisées sont des paires clé/valeur utilisées pour stocker les métadonnées personnalisées d'un fichier Google Drive (telles que des tags), les ID d'autres datastores, les informations partagées entre les applications de workflow, etc. Par exemple, vous pouvez ajouter des propriétés de fichier à tous les documents générés par le service commercial au cours du premier trimestre.

Pour ajouter des propriétés visibles par toutes les applications, utilisez le champ properties de la ressource files. Pour ajouter des propriétés limitées à votre application, utilisez le champ appProperties de la ressource files.

Remarque :Si vous utilisez l'ancienne version de l'API Google Drive (v2), utilisez la ressource properties pour ajouter des propriétés à votre application à l'aide de properties.insert. Pour obtenir la liste complète des différences entre les versions, consultez la documentation de référence de l'API Drive v2 et v3.

Les propriétés peuvent également être utilisées dans des expressions de recherche.

Il s'agit de la structure d'une propriété type qui peut être utilisée pour stocker l'ID de base de données d'un fichier Drive dans le fichier.

API Drive v3

"appProperties": {
  "additionalID": "ID",
}

API Drive version 2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

Utiliser des propriétés de fichier personnalisées

Cette section explique comment effectuer certaines tâches liées aux propriétés de fichier personnalisées qui affectent toutes les applications.

Remarque :L'interface utilisateur de Google Drive n'inclut pas de moyen intégré de modifier les propriétés personnalisées.

Ajouter ou mettre à jour des propriétés de fichier personnalisées

Pour ajouter ou mettre à jour des propriétés visibles par toutes les applications, utilisez la méthode files.update pour définir le champ properties de la ressource files.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Vous pouvez également ajouter une propriété personnalisée à un fichier à l'aide du service Drive avancé dans Google Apps Script. Pour en savoir plus, consultez la section Ajouter des propriétés personnalisées.

Obtenir ou lister des propriétés de fichier personnalisées

Pour afficher les propriétés visibles par toutes les applications, utilisez la méthode files.get pour récupérer les propriétés de fichier personnalisées du fichier.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

La réponse se compose d'un objet properties contenant une collection de paires clé-valeur.

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Supprimer des propriétés de fichier personnalisées

Pour supprimer les valeurs de propriété visibles par toutes les applications, utilisez la méthode files.update pour définir le champ properties de la ressource files sur "null".

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "name": null
}

Pour afficher la modification, appelez la méthode files.get pour récupérer l'objet properties du fichier.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

Limites des propriétés de fichier personnalisées

Les propriétés personnalisées sont soumises aux limites suivantes:

• Le nombre de propriétés personnalisées est limité à 100 par fichier, toutes sources confondues.
• 30 propriétés publiques maximum par fichier, totalisées pour toutes les sources.
• 30 propriétés privées maximum par fichier d'une application donnée.
• 124 octets maximum par chaîne de propriété (y compris la clé et la valeur) encodés en UTF-8. Par exemple, une propriété avec une clé comportant 10 caractères ne peut pas comporter plus de 114 caractères. De même, une propriété qui nécessite 100 caractères pour la valeur peut utiliser jusqu'à 24 caractères pour la clé.

Pour en savoir plus, consultez la ressource files. Pour l'API Drive v2, consultez la ressource properties.

Accéder aux propriétés de fichier personnalisées privées

Vous ne pouvez récupérer des propriétés privées à l'aide du champ appProperties que via une requête authentifiée qui utilise un jeton d'accès obtenu avec un ID client OAuth 2.0. Vous ne pouvez pas utiliser une clé API pour récupérer des propriétés privées.