How to Use Google Workspace Drive API to Manage Custom File Properties

Google Drive is excellent for organizing files into hierarchical folders, but folders are fundamentally limited. What if a legal contract belongs in the “2024 Contracts” folder, but it also applies to the “Project Alpha” team, and it also needs a status tag of “Pending Signature”? If you rely solely on folders, you either create confusing shortcuts or duplicate the file. The enterprise solution is to abandon rigid folders and rely on metadata. Using the Google Workspace Drive API, you can attach invisible, searchable key-value pairs called Custom Properties directly to any file.

Understanding Drive Properties

The Drive API supports two distinct types of custom properties:

1. Private Properties: These key-value pairs are completely invisible to everyone except the specific application that created them. This is perfect for storing internal database IDs (e.g., linking a Google Doc to a specific row in your company’s SQL database).
2. Public Properties: These are visible to all applications and, more importantly, they are indexed by Google’s search engine, meaning users can search for them using advanced query syntax.

Step 1: Add a Custom Property to a File

To attach a property, you use the files().update() method. You are not changing the file’s content or title; you are only patching the metadata.

Here is how you add a public property using the Python client library:

file_id = '1aB2c3D4e5F6g7H8i9J0'

# Define the properties as a dictionary
metadata = {
    'properties': {
        'projectCode': 'ALPHA-99',
        'documentStatus': 'Pending_Signature'
    }
}

# Apply the properties to the file
service.files().update(
    fileId=file_id,
    body=metadata
).execute()

print("Properties successfully attached.")

Because we used the properties field, these are public. (If you wanted private properties, you would use the appProperties field instead).

Step 2: Read Custom Properties

By default, when you perform a files().get() request, the Google Drive API tries to save bandwidth by returning only basic information (like the ID and Name). It does not return custom properties unless you explicitly ask for them using the fields parameter.

response = service.files().get(
    fileId=file_id,
    fields='id, name, properties'
).execute()

# Extract the properties dictionary safely
file_properties = response.get('properties', {})

print(f"Project Code: {file_properties.get('projectCode')}")

Step 3: Search Using Custom Properties (The Real Power)

The true power of custom properties is that they act like tags in a database. You can instantly find all files across a massive corporate Drive that share a specific property, regardless of which nested folders they are hidden inside.

To do this, you use the files().list() method with a specific q (query) parameter syntax.

To find all files where the projectCode is exactly ALPHA-99:

query = "properties has { key='projectCode' and value='ALPHA-99' }"

results = service.files().list(
    q=query,
    fields='files(id, name)'
).execute()

for f in results.get('files', []):
    print(f"Found match: {f['name']}")

Crucial Note: You must use the exact syntax properties has { ... }. If you are searching for private properties, you would change it to appProperties has { ... }.

Step 4: Delete a Custom Property

If a contract is finally signed and you want to remove the “Pending_Signature” tag entirely (rather than just changing its value), you issue an update() request but set the specific key’s value to None (or null in JSON).

metadata = {
    'properties': {
        'documentStatus': None
    }
}

service.files().update(
    fileId=file_id,
    body=metadata
).execute()

By utilizing Custom Properties, you transform Google Drive from a simple file storage locker into a dynamic, searchable, relational document management system.