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 des métadonnées personnalisées pour un fichier Google Drive (telles que des balises), des ID d'autres magasins de données, des informations partagées entre des 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 v2

{
  '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 ne propose pas de méthode intégrée pour 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:

• 100 propriétés personnalisées maximum par fichier, totalisées pour toutes les sources.
• 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) en encodage UTF-8. Par exemple, la valeur d'une propriété dont la clé comporte 10 caractères ne peut pas dépasser 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.