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
.
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.
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) encodés en UTF-8. Par exemple, une propriété avec une clé de 10 caractères ne peut avoir qu'une valeur 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.