Enabling Team Drives

To support Team Drives in your application, you must make a number of changes so that your app can create and manage Team Drives and files that they contain.

If you don't upgrade your application, then it will continue to be supported in a backwards-compatible manner, but it will not be able to access Team Drives or files contained within Team Drives.

Behavioral differences

Because Team Drives follow different organization, sharing, and ownership models, some Drive operations are not permitted for content in Team Drives. Additionally, fields related to permissions and ownership are populated differently.

File resources

The following fields are only populated for files located within a Team Drive:

  • hasAugmentedPermissions — Whether any users are granted file access directly on this file
  • capabilities/canMoveTeamDriveItem — Whether the current user can move this Team Drive item by changing its parent
  • capabilities/canReadTeamDrive — Whether the current user has read access to the Team Drive to which this file belongs.
  • teamDriveId — The ID of the Team Drive within which the file is located
  • trashingUser — If the file has been explicitly trashed, the user who trashed it.
  • trashedTime — The time that the item was trashed.

The following fields are not populated for files located within a Team Drive:

  • permissions — Due to the potential size of Team Drive ACLs, permissions are not returned as part of files. Use the permissions.list method, which supports pagination, to list permissions for a file within a Team Drive or the Team Drive resource.
  • owners, ownerNames, ownedByMe — Files within a Team Drive are owned by the Team Drive, not individual users.
  • folderColorRgb — Folders cannot be colored individually
  • shared — All items in a Team Drive are shared.
  • writersCanShare — It is currently not possible to restrict sharing by role in Team Drives.

The following fields are only set when the user has been granted file access permissions on an item:

  • sharedWithMeDate
  • sharingUser

The following fields require special consideration when you use them with Team Drives:

  • parents.isRoot — This field is only true for the My Drive root folder; it is false for the Team Drive top-level folder.
  • parents — A parent does not appear in the parents list if the requesting user is a not a member of the Team Drive and does not have access to the parent. In addition, with the exception of the top level folder, the parents list must contain exactly one item if the file is located within a Team Drive.

Permissions resource

The following field is only populated for files located within a Team Drive:

  • teamDrivePermissionDetails — A list of condensed Permissions that are on or inherited by this Team Drive file. This is an output-only field which is present only for Team Drive items.

Additional changes:

  • A new role organizer has been defined.
  • permissions.list now supports pagination.

Changes resource

The following new fields are available:

  • type — The type of the change. Possible values are file and teamDrive.
  • teamDriveId — The ID of the Team Drive associated with this change.
  • teamDrive — The updated state of the Team Drive. Present if the type is teamDrive and the user is still a member of the Team Drive.

Additional changes may be required for applictions that need to sync content with Team Drives or track activity. See tracking changes in Team Drives for details.

Opt-in to Team Drive content

To access content that is contained in a Team Drive, you need to make changes to your app. The size of this change depends on whether your app is affected by the behavioral changes associated with Team Drives.

Apps unaffected by Team Drive behavior

If your application isn't affected by the behavioral differences, then you only need to include the supportsTeamDrives=true query parameter in requests. This is an acknowledgement that the application is aware of behavioral differences of files contained in Team Drives.

The following methods require supportTeamDrives=true when working with Team Drives content:

  • files.get
  • files.list
  • files.create
  • files.update
  • files.copy
  • files.delete
  • changes.list
  • changes.getStartPageToken
  • permissions.list
  • permissions.get
  • permissions.create
  • permissions.update
  • permissions.delete

Apps that are affected by Team Drive behavior

Applications that read or modify permissions, track changes, or need to search across multiple corpora require additional changes. The following sections highlight the changes that may be required for some apps.

Including Team Drive content files.list

Team Drives adds the capability to search files within a specific Team Drive or search across all Team Drives.

The files.list request has several parameters specific to Team Drives:

  • teamDriveId — ID of Team Drive to search.
  • includeTeamDriveItems — Whether Team Drive items should be included in results. If not present or set to false, then Team Drive items are not returned.
  • corpora — Comma-separated list of bodies of items (files/documents) to which the query applies. Supported bodies are user, domain, teamDrive, and allTeamDrives. allTeamDrives must be combined with user; all other values must be used in isolation. Prefer user or teamDrive to allTeamDrives for efficiency.
  • supportsTeamDrives — Whether the requesting application supports Team Drives. If false, then Team Drive items are not included in the response.

The following query modes are specific to Team Drives:

includeTeamDriveItems corpora Query Description
true user Queries files that the user has accessed, including both Team Drive and non-Team Drive files.
true teamDrive Queries all items in the specified Team Drive. teamDriveId must be specified in the request.
true user,allTeamDrives Queries files that the user has accessed and all Team Drives in which they are a member. Note that the response may include incompleteSearch : true, indicating that some corpora were not searched for this request.
true domain Queries files that are shared to the domain, including both Team Drive and non-Team Drive files.

Tracking changes in Team Drives

The changes.list method has several parameters specific to Team Drives:
  • teamDriveId — The Team Drive from which changes will be returned. If specified, the change IDs refer to changes within the Team Drive, not changes to the files seen by the user. To refer to a specific Team Drive change, both the Team Drive ID and change ID must be used as an identifier.
  • supportsTeamDrives — Whether the requesting application supports Team Drives. If false, then Team Drive items, including both Team Drives and files within a Team Drive, are not returned.

The changes.list method also supports:

  • includeTeamDriveItems — Whether Team Drive files or changes should be included in the list of changes.

The following query modes are specific to Team Drives:

  • changes.list with includeTeamDriveItems=true — Changes are reflective of changes to files inside or outside of Team Drives that the user has accessed, as well as changes to Team Drives in which the user is a member.
  • changes.list with includeTeamDriveItems=true and teamDriveId is specified — Changes are reflective of changes to the particular Team Drive that was specified and items inside that Team Drive.

For additional details about change log behavior, see Change Logs.

Enabling "new" and "open with" support in Drive

Drive apps must also acknowledge Team Drive support in the Google Cloud Console. To enable UI integration for content in Team Drives, check the Team Drives support option on the Drive UI Integration settings page.

Using the file picker with Team Drives

The file picker supports selecting items in Team Drives. For details around enabling Team Drives support and adding Team Drives view in file picker, see Picker API.

Send feedback about...

Need help? Visit our support page.