Custom file properties are key-value pairs used to store custom metadata for a Google Drive file (such as tags), IDs from other data stores, information shared between workflow applications, and so on. For example, you can add file properties to all documents generated by the sales department in Q1.
To add properties visible to all applications, use the properties
field of the
files
resource. To add properties
restricted to your app, use the appProperties
field of the files
resource.
Properties can also be used in search expressions.
This is the structure of a typical property that might be used to store a Drive file's database ID on the file.
Drive API v3
"appProperties": {
"additionalID": "ID",
}
Drive API v2
{
'key': 'additionalID',
'value': 'ID',
'visibility': 'PRIVATE'
}
Working with custom file properties
The section explains how to perform some custom file property-related tasks that affect all applications.
Add or update custom file properties
To add or update properties visible to all applications, use the
files.update
method to set the
properties
field of the files
resource.
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{ "properties": { "name": "wrench", "mass": "1.3kg", "count": "3" } }
You can also add a custom property to a file using the advanced Drive service in Google Apps Script. For more information, see Adding custom properties.
Get or list custom file properties
To view properties visible to all applications, use the
files.get
method to retrieve the
custom file properties for the file.
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=properties
The response consists of a properties
object that contains a collection of
key-value pairs.
{ "properties": { "name": "wrench", "mass": "1.3kg", "count": "3" } }
Delete custom file properties
To delete property values visible to all applications, use the
files.update
method to set the
properties
field of the files
resource to null.
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{ "name": null }
To view the change, call the
files.get
method to retrieve the
properties
object for the file.
{ "properties": { "mass": "1.3kg", "count": "3" } }
Limits of custom file properties
Custom properties have the following limits:
- Maximum of 100 custom properties per file, totaled from all sources.
- Maximum of 30 public properties per file, totaled from all sources.
- Maximum of 30 private properties per file from any one application.
- Maximum of 124 bytes per property string (including both key and value) in UTF-8 encoding. For example, a property with a key that's 10 characters long can only have 114 characters in the value. Similarly, a property that requires 100 characters for the value can use up to 24 characters for the key.
For more information, see the files
resource. For Drive API v2, see the
properties
resource.
Access private custom file properties
You can only retrieve private properties using the appProperties
field through
an authenticated request that uses an access token obtained with an OAuth 2.0
client ID. You cannot use an API key to retrieve private properties.