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 tags), des ID provenant d'autres data stores, des 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 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 réservées à votre application, utilisez le champ appProperties de la ressource files.

Les propriétés peuvent également être utilisées dans les 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 sur le fichier.

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

{
  '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.

Ajouter ou modifier 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 afin de 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 Ajouter des propriétés personnalisées.

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

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

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 afin de 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 afin de récupérer l'objet properties pour le 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 maximal de propriétés personnalisées par fichier est de 100, toutes sources confondues.
• Maximum de 30 propriétés publiques par fichier, toutes sources confondues.
• Vous ne pouvez pas ajouter plus de 30 propriétés privées par fichier à partir d'une même application.
• La taille maximale est de 124 octets par chaîne de propriété (y compris la clé et la valeur) en encodage UTF-8. Par exemple, une propriété dont la clé comporte 10 caractères ne peut avoir que 114 caractères dans la valeur. De même, une propriété dont la valeur nécessite 100 caractères 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 les propriétés privées à l'aide du champ appProperties que par le biais d'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 de clé API pour récupérer des propriétés privées.