This guide contains tasks related to managing shared drives, such as creating shared drives and managing members and permissions, using the Google Drive API.
If you want to specify the fields to return in the response, you can set the fields
system parameter with any method of the drives
resource. If you don't specify the fields
parameter, the server returns a default set of fields specific to the method. For example, the list
method returns only the kind
, id
, and name
fields for each shared drive. For more information, see Return specific fields.
To learn more about shared drive folder limits, see Shared drive folder limits.
Create a shared drive
To create a shared drive, use the create
method on the drives
resource with the requestId
parameter.
The requestId
parameter identifies the logical attempt for idempotent creation of a shared drive. If the request times out or returns an indeterminate backend error, the same request can be repeated and won't create duplicates. The requestId
and body of the request must remain the same.
The following code sample shows how to create a shared drive:
Java
Python
Node.js
PHP
.NET
Calls to the create
method are idempotent.
If the shared drive was successfully created on a previous request or due to a retry, the method returns an instance of the drives
resource. Sometimes, such as after a prolonged time or if the body of the request has changed, a 409
error might be returned indicating the requestId
must be discarded.
Get a shared drive
To get metadata for a shared drive, use the get
method on the drives
resource with the driveId
path parameter. If you don't know the drive ID, you can list all shared drives using the list
method.
The get
method returns a shared drive as an instance of a drives
resource.
To issue the request as a domain administrator, set the useDomainAdminAccess
query parameter to true
. For more information, see Manage shared drives as domain administrators.
List shared drives
To list a user's shared drives, use the list
method on the drives
resource. The method returns a list of shared drives.
Pass the following query parameters to customize pagination of, or to filter, shared drives:
pageSize
: The maximum number of shared drives to return per page.pageToken
: A page token, received from a previous list call. Provide this token to retrieve the subsequent page.q
: Query string for searching shared drives. For more information, see Search for shared drives.useDomainAdminAccess
: Set totrue
to issue the request as a domain administrator to return all shared drives of the domain in which the requester is an administrator. For more information, see Manage shared drives as domain administrators.
Update a shared drive
To update the metadata for a shared drive, use the update
method on the drives
resource with the driveId
path parameter.
The method returns a shared drive as an instance of a drives
resource.
To issue the request as a domain administrator, set the useDomainAdminAccess
query parameter to true
. For more information, see Manage shared drives as domain administrators.
Hide and unhide a shared drive
To hide a shared drive from the default view, use the hide
method on the drives
resource with the driveId
parameter.
When a shared drive is hidden, Drive marks the shared drive resource as hidden=true
. Hidden shared drives don't appear in the Drive UI or in the list of returned files.
To restore a shared drive to the default view, use the unhide
method on the drives
resource with the driveId
parameter.
Both methods return a shared drive as an instance of a drives
resource.
Delete a shared drive
To permanently delete a shared drive, use the delete
method on the drives
resource with the driveId
parameter.
Before deleting a shared drive, all content in the shared drive must be moved to the trash or deleted. The user must also have role=organizer
on the shared drive folder. For more information, see Trash or delete files and folders.
Pass the following query parameters to filter shared drives:
useDomainAdminAccess
: Set totrue
to issue the request as a domain administrator to return all shared drives of the domain in which the requester is an administrator. For more information, see Manage shared drives as domain administrators.allowItemDeletion
: Set totrue
to delete items within the shared drive. Only supported whenuseDomainAdminAccess
is also set totrue
.
Add or remove shared drive members
Add or remove shared drive members using the permissions
resource.
To add a member, create the permission on the shared drive. Permission methods can also be used on individual files within a shared drive to grant members additional privileges or allow non-members to collaborate on specific items.
For more information and sample code, see Share files, folders, and drives.
Manage shared drives as domain administrators
Apply the useDomainAdminAccess
parameter with the drives
and permissions
resources to manage shared drives across an organization.
Users calling these methods with useDomainAdminAccess=true
must have the Drive and Docs
administrator privilege. Administrators can search for shared drives or update permissions for shared drives owned by their organization, regardless of the administrator's membership in any given shared drive.
When using service accounts, you might have to impersonate an authenticated administrator using service account impersonation. Note that service accounts do not belong to your Google Workspace domain, unlike user accounts. If you share Google Workspace assets, like documents or events, with your entire Google Workspace domain, they're not shared with service accounts. For more information, see Service accounts overview.
Recover a shared drive that doesn't have an organizer
The following code sample shows how to recover shared drives that no longer have an organizer.
Java
Python
Node.js
PHP
.NET
Prevent users from downloading, printing, or copying your file
You can limit how users can download, print, and copy files within shared drives.
To determine whether the user can change organizer-applied download restrictions of a shared drive, check the capabilities.canChangeDownloadRestriction
boolean field. If capabilities.canChangeDownloadRestriction
is set to true
, download restrictions can be applied to the shared drive. For more information, see Understand file capabilities.
The drives
resource contains a collection of boolean restrictions
fields used to indicate whether an action can be performed on a shared drive. Restrictions apply to a shared drive or items inside a shared drive. Restrictions can be set using the drives.update
method.
To apply download restrictions to a shared drive, a shared drive manager can set the restrictions.downloadRestriction
field of the drives
resource using the DownloadRestriction
object. Setting the restrictedForReaders
boolean field to true
declares that both download and copy are restricted for readers. Setting the restrictedForWriters
boolean field to true
declares that both download and copy are restricted for writers. Note that if the restrictedForWriters
field is true
, download and copy is also restricted for readers. Similarly, setting restrictedForWriters
to true
and restrictedForReaders
to false
is equivalent to setting both restrictedForWriters
and restrictedForReaders
to true
.
Backward compatibility
With the introduction of the DownloadRestriction
object, the functionality of the restrictions.copyRequiresWriterPermission
boolean field has been updated.
Now, setting restrictions.copyRequiresWriterPermission
to true
updates the restrictedForReaders
boolean field of the DownloadRestriction
object to true
to declare that both download and copy are restricted for readers.
Setting the copyRequiresWriterPermission
field to false
updates both the restrictedForWriters
and restrictedForReaders
fields to false
. This means download or copy restriction settings are removed for all users.
Fields that control download, print, and copy features
The following table lists drives
resource fields that affect download, print, and copy functionality:
Field | Description | Version |
---|---|---|
capabilities.canCopy | Whether the current user can copy files in a shared drive. | v2 & v3 |
capabilities.canDownload | Whether the current user can download files in a shared drive. | v2 & v3 |
capabilities.canChangeCopyRequiresWriterPermission | Whether the current user can change the copyRequiresWriterPermission restriction of a shared drive. | v2 & v3 |
capabilities.canResetDriveRestrictions | Whether the current user can reset the shared drive restrictions to defaults. | v2 & v3 |
capabilities.canChangeDownloadRestriction | Whether the current user can change the download restriction of a shared drive. | v3 only |
restrictions.copyRequiresWriterPermission | Whether the options to copy, print, or download files inside a shared drive are disabled for readers and commenters. When true , it sets the similarly named field to true for any file inside this shared drive. | v2 & v3 |
restrictions.downloadRestriction | The download restrictions applied by shared drive managers. | v3 only |
Folder limits
Shared drive folders have some storage limits. For information, see Shared drive limits in Google Drive.
Item cap
Each user's shared drive has a limit of 500,000 items, including files, folders, and shortcuts.
When the limit is reached, the shared drive can no longer accept items. To resume receiving files, users must permanently delete items from the shared drive. Note that items in the trash count toward the limit, but permanently-deleted items don't. For more information, see Trash or delete files and folders.
Folder-depth limit
A folder in a shared drive can't contain more than 100 levels of nested folders. This means that a child folder cannot be stored under a folder that's more than 99 levels deep. This limitation only applies to child folders.
Attempts to add more than 100 levels of folders returns a teamDriveHierarchyTooDeep
HTTP status code response.