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
— Deprecated. Usecapabilities/canMoveItemWithinTeamDrive
orcapabilities/canMoveItemOutOfTeamDrive
.capabilities/canDeleteChildren
— Whether the current user can delete children of this folder.capabilities/canMoveChildrenOutOfTeamDrive
— Whether the current user can move children of this folder outside of the Team Drive.capabilities/canMoveChildrenWithinTeamDrive
— Whether the current user can move children of this folder within the Team Drive.capabilities/canMoveItemOutOfTeamDrive
— Whether the current user can move this Team Drive item outside of the Team Drive by changing its parent.capabilities/canMoveItemWithinTeamDrive
— Whether the current user can move this Team Drive item within the Team Drive.capabilities/canReadTeamDrive
— Whether the current user has read access to the Team Drive to which this file belongs.capabilities/canTrashChildren
— Whether the current user can trash children of this folder.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 thepermissions.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 individuallyshared
— 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.capabilities/canRemoveChildren
— Usecapabilities/canDeleteChildren
orcapabilities/canTrashChildren
.
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:
- Two new roles of
organizer
andfileOrganizer
have been defined. permissions.list
now supports pagination.
Changes resource
The following new fields are available:
type
— The type of the change. Possible values arefile
andteamDrive
.teamDriveId
— The ID of the Team Drive associated with this change.teamDrive
— The updated state of the Team Drive. Present if thetype
isteamDrive
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 areuser
,domain
,teamDrive
, andallTeamDrives
.allTeamDrives
must be combined withuser
; all other values must be used in isolation. Preferuser
orteamDrive
toallTeamDrives
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
Thechanges.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
withincludeTeamDriveItems=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
withincludeTeamDriveItems=true
andteamDriveId
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.