-
Notifications
You must be signed in to change notification settings - Fork 0
Users Drive Permissions
- API documentation
- Query documentation
- Permission Matches
- Definitions
- Manage file permissions/sharing
- Display file permissions/sharing
- Delete all ACLs except owner from a file
- https://developers.google.com/drive/api/v3/reference/permissions
- https://developers.google.com/drive/api/v3/ref-single-parent
- https://developers.google.com/drive/api/v3/search-files
- https://developers.google.com/drive/api/v3/ref-search-terms
<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= id:<String>
<UserItem> ::= <EmailAddress>|<UniqueID>|<String>
<DrivePermissionsFieldName> ::=
additionalroles|
allowfilediscovery|
basicpermissions|
deleted|
displayname|
domain|
emailaddress|
expirationdate|
expirationtime|
id|
name|
pendingowner|
permissiondetails|
photolink|
role|
type|
view|
withlink
<DrivePermissionsFieldNameList> ::= "<DrivePermissionsFieldName>(,<DrivePermissionsFieldName>)*"
basicpermissions
is equivalent to:
permissions.allowFileDiscovery,
permissions.deleted,
permissions.domain,
permissions.emailAddress,
permissions.expirationTime,
permissions.id,
permissions.role,
permissions.type
In particular, this omits these fields:
permissions.displayName,
permissions.permissionDetails,
permissions.photoLink,
permissions.teamDrivePermissionDetails
This allows you to select the essential permission fields without enumerating them. Of course,
you can specify permissions
to get all of the fields, enumerate the specific fields you want or
specify basicpermissions
and additional permission fields, e.g., permissions.displayName
.
<DriveOrderByFieldName> ::=
createddate|createdtime|
folder|
modifiedbyme|modifiedbymedate|modifiedbymetime|modifiedbyuser|
modifieddate|modifiedtime|
name|
name_natural|
quotabytesused|quotaused|
recency|
sharedwithmedate|sharedwithmetime|
starred|
title|
title_natural|
viewedbymedate|viewedbymetime
<DriveFileACLRole> ::=
commenter|
contentmanager|fileorganizer|
contributor|editor|writer|
manager|organizer|owner|
reader|viewer
<DriveFileACLRoleList> ::= "<DriveFileACLRole>(,<DriveFileACLRole>)*"
<DriveFileACLType> ::= anyone|domain|group|user
<DriveFilePermission> ::=
anyone|anyonewithlink|
user:<EmailAddress>|group:<EmailAddress>|
domain:<DomainName>|domainwithlink:<DomainName>;<DriveFileACLRole>
<DriveFilePermissionID> ::=
anyone|anyonewithlink|id:<String>
<DriveFilePermissionIDorEmail> ::=
<DriveFilePermissionID>|<EmailAddress>
<DriveFilePermissionList> ::=
"<DriveFilePermission>(,<DriveFilePermission)*"
<DriveFilePermissionIDList> ::=
"<DriveFilePermissionID>(,<DriveFilePermissionID>)*"
<DriveFilePermissionEntity> ::=
<DriveFilePermissionList> |
(json [charset <Charset>] <JSONData>)|(json file <FileName> [charset <Charset>]) |
<FileSelector> |
<CSVFileSelector> |
<CSVkmdSelector> |
<CSVDataSelector>
<DriveFilePermissionIDEntity> ::=
<DriveFilePermissionIDList> |
(json [charset <Charset>] <JSONData>)|(json file <FileName> [charset <Charset>]) |
<FileSelector> |
<CSVFileSelector> |
<CSVkmdSelector> |
<CSVDataSelector>
gam <UserTypeEntity> create|add drivefileacl <DriveFileEntity>
anyone|(user <UserItem>)|(group <GroupItem>)|(domain <DomainName>) (role <DriveFileACLRole>)
[withlink|(allowfilediscovery|discoverable [<Boolean>])] [expiration <Time>]
[movetonewownersroot [<Boolean>]]
[sendemail] [emailmessage <String>]
[updatesheetprotectedranges [<Boolean>]]
[showtitles] [nodetails|(csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]])]
From the Google Drive API documentation.
-
movetonewownersroot
- This parameter only takes effect if the item is not in a shared drive and the request is attempting to transfer the ownership of the item.-
false
- Parents are not changed. The file is an orphan for the new owner. This is the default. -
true
- The item is moved to the new owner's My Drive root folder and all prior parents removed. The file is inShared with me
for the old owner.
-
To transfer ownership of a file/folder and place it in a specific folder on the new owner's My Drive, do:
gam <UserTypeEntity> transfer ownership <DriveFileEntity> <UserItem>
[<DriveFileParentAttribute>] norecursion
The options withlink|allowfilediscovery|discoverable
are only valid for ACLs to anyone
or domain
.
The option expiration <Time>
is only valid for role commenter|reader|viewer
.
The option updatesheetprotectedranges
only applies to items in <DriveFileEntity>
that are Google Sheets.
-
updatesheetprotectedranges false
or option omitted- Sheet Protected Ranges are not updated
-
updatesheetprotectedranges
orupdatesheetprotectedranges true
- Sheet Protected Ranges are updated to reflect the new ACL; additional API calls are required.
- ACLs with role reader or commenter will not be added to protected ranges
- ACLs with role writer or higher will be added to existing protected ranges
- Sheet Protected Ranges are updated to reflect the new ACL; additional API calls are required.
By default, the file ID is displayed in the output; to see the file name, use the showtitles
option; this requires an additional API call per file.
By default, when an ACL is created, GAM outputs details of the ACL as indented keywords and values.
-
nodetails
- Suppress the details output. -
csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]
- Output the details in CSV format.
gam <UserTypeEntity> update drivefileacl <DriveFileEntity> <DriveFilePermissionIDorEmail>
(role <DriveFileACLRole>) [expiration <Time>] [removeexpiration [<Boolean>]]
[updatesheetprotectedranges [<Boolean>]]
[showtitles] [nodetails|(csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]])]
There is no change of parents when a new user is updated to be a file's owner.
The option updatesheetprotectedranges
only applies to items in <DriveFileEntity>
that are Google Sheets.
-
updatesheetprotectedranges false
or option omitted- Sheet Protected Ranges are not updated
-
updatesheetprotectedranges
orupdatesheetprotectedranges true
- Sheet Protected Ranges are updated to reflect the updated ACL; additional API calls are required.
- ACLs with role reader or commenter will be removed from existing protected ranges
- ACLs with role writer or higher will be added to existing protected ranges
- Sheet Protected Ranges are updated to reflect the updated ACL; additional API calls are required.
By default, the file ID is displayed in the output; to see the file name, use the showtitles
option; this requires an additional API call per file.
By default, when an ACL is updated, GAM outputs details of the ACL as indented keywords and values.
-
nodetails
- Suppress the details output. -
csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]
- Output the details in CSV format.
gam <UserTypeEntity> delete|del drivefileacl <DriveFileEntity> <DriveFilePermissionIDorEmail>
[updatesheetprotectedranges [<Boolean>]]
[showtitles]
The option updatesheetprotectedranges
only applies to items in <DriveFileEntity>
that are Google Sheets.
-
updatesheetprotectedranges false
or option omitted- Sheet Protected Ranges are not updated
-
updatesheetprotectedranges
orupdatesheetprotectedranges true
- Sheet Protected Ranges are updated to reflect the deleted ACL; additional API calls are required.
- ACLs with any role will be removed from existing protected ranges
- Sheet Protected Ranges are updated to reflect the deleted ACL; additional API calls are required.
By default, the file ID is displayed in the output; to see the file name, use the showtitles
option; this requires an additional API call per file.
gam <UserTypeEntity> create|add permissions <DriveFileEntity> <DriveFilePermissionEntity>
[expiration <Time>] [sendemail] [emailmessage <String>]
[movetonewownersroot [<Boolean>]]
<PermissionMatch>* [<PermissionMatchAction>]
The option expiration <Time>
is only valid for role commenter|reader|viewer
.
From the Google Drive API documentation.
-
movetonewownersroot
- This parameter only takes effect if the item is not in a shared drive and the request is attempting to transfer the ownership of the item.-
false
- Parents are not changed. The file is an orphan for the new owner. This is the default. -
true
- The item is moved to the new owner's My Drive root folder and all prior parents removed. The file is an orphan for the old owner.
-
Permission matching only applies when the (json [charset <Charset>] <JSONData>)|(json file <FileName> [charset <Charset>])
variant of <DriveFilePermissionEntity>
and <DriveFilePermissionIDEntity>
is used.
When adding permissions from JSON data, there is a default match: pm not role owner em
that disables ownership changes.
If you want to process all permissions, enter pm em
to clear the default match.
When adding permissions from JSON data, permissions with deleted
true are never processed.
gam <UserTypeEntity> delete permissions <DriveFileEntity> <DriveFilePermissionIDEntity>
<PermissionMatch>* [<PermissionMatchAction>]
When deleting permissions from JSON data, permissions with role owner
true are never processed.
gam <UserTypeEntity> info drivefileacl <DriveFileEntity> <DriveFilePermissionIDorEmail>
[showtitles] [formatjson]
gam <UserTypeEntity> show drivefileacls <DriveFileEntity>
(role|roles <DriveFileACLRoleList>)*
<PermissionMatch>* [<PermissionMatchAction>] [pmselect]
[includepermissionsforview published]
[oneitemperrow] [<DrivePermissionsFieldName>*|(fields <DrivePermissionsFieldNameList>)]
[showtitles|(addtitle <String>)]]
(orderby <DriveFileOrderByFieldName> [ascending|descending])*
[formatjson]
gam <UserTypeEntity> print drivefileacls <DriveFileEntity> [todrive <ToDriveAttributes>*]
(role|roles <DriveFileACLRoleList>)*
<PermissionMatch>* [<PermissionMatchAction>] [pmselect]
[includepermissionsforview published]
[oneitemperrow] [<DrivePermissionsFieldName>*|(fields <DrivePermissionsFieldNameList>)]
[showtitles|(addtitle <String>)]]
(orderby <DriveFileOrderByFieldName> [ascending|descending])*
[formatjson [quotechar <Character>]]
By default, the file ID is displayed in the output; to see the file name, use the showtitles
option; this requires an additional API call per file. If you are reading the file IDs from a
CSV file that also includes the file name, you can use the addtitle
option to supply the file name.
By default, all files specified are displayed; use the following option to select a subset of those files.
-
<PermissionMatch>* [<PermissionMatchAction>] pmselect
- Use permission matching to select files
By default, all ACLS are displayed; use the following option to select a subset of the ACLS to display.
-
role|roles <DriveFileACLRoleList>
- Display ACLs for the specified roles only. -
<PermissionMatch>* [<PermissionMatchAction>]
- Use permission matching to display a subset of the ACLs for each file; this only applies whenpmselect
is not specified
With print drivefileacls
or show drivefileacls formatjson
, the ACLs selected for display are all output on one row/line as a repeating item with the matching file id.
When oneitemperrow
is specified, each ACL is output on a separate row/line with the matching file id. This simplifies processing the CSV file with subsequent Gam commands.
By default, when writing CSV files, Gam uses a quote character of double quote "
. The quote character is used to enclose columns that contain
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
When using the formatjson
option, double quotes are used extensively in the data resulting in hard to read/process output.
The quotechar <Character>
option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
quotechar
defaults to gam.cfg/csv_output_quote_char
. When uploading CSV files to Google, double quote "
should be used.
For example, to get the ACLs for your Team Drives with the Team Drive name included in the output:
gam redirect csv ./TeamDrives.csv print teamdrives
gam redirect csv ./TeamDriveACLs.csv multiprocess csv ./TeamDrives.csv gam print drivefileacls teamdriveid "~id" addtitle "~name" fields id,domain,emailaddress,role,type,deleted
Get the current ACLs.
gam redirect csv ./Permissions.csv user <UserItem> print drivefileacls <DriveFileID> oneitemperrow
Inspect Permissions.csv, verify that you want to proceed.
gam config csv_input_row_drop_filter "permission.role:regex:(owner)|(organizer)" csv ./Permissions.csv gam user "~Owner" delete drivefileacl "~id" "id:~~permission.id~~"
Need more help? Ask on the GAM Discussion Group
Update History
Installation
- How to Install Advanced GAM
- How to Update Advanced GAM
- How to Upgrade from Standard GAM
- How to Upgrade from GAMADV-X or GAMADV-XTD
- Install GAM as Python Library
- GAMADV-XTD3 on Chrome OS Devices
- GAMADV-XTD3 on Android Devices
- Google Network Addresses
- HTTPS Proxy
- SSL Root CA Certificates
- How to Uninstall Advanced GAM
Configuration
- Authorization
- GAM Configuration
- Running GAMADV-XTD3 securely on a Google Compute Engine
- Using GAMADV-XTD3 with a delegated admin service account
- Using GAMADV-XTD3 with a YubiKey
Notes and Information
- Upgrade Benefits
- Questions? Visit the GAM Discussion Forum
- Scripts
- Other Resources
- Drive REST API v3
- BNF Syntax
- GAM Return Codes
- Python Regular Expressions
- Rclone
- Cross-Referenced Command Summary
Definitions
Command Processing
- Bulk Processing
- Command Line Parsing
- Command Logging and Progress
- Command data from Google Docs and Sheets
- CSV Input Filtering
- CSV Output Filtering
- Meta Commands and File Redirection
- Permission matches
- Tag Replace
- Todrive
Collections
Client Access
- Addresses
- Administrators
- Alert Center
- Aliases
- Calendars
- Calendars - Access
- Calendars - Events
- Chrome Auto Update Expiration Counts
- Chrome Browser Cloud Management
- Chrome Device Needs Attention Counts
- Chrome Installed Apps Counts
- Chrome Policies
- Chrome Printers
- Chrome Version Counts
- Chrome Version History
- ChromeOS Devices
- Classroom - Courses
- Classroom - Guardians
- Classroom - Invitations
- Classroom - Membership
- Cloud Channel
- Cloud Identity Devices
- Cloud Identity Groups
- Cloud Identity Groups - Membership
- Context Aware Access Levels
- Customer
- Domains
- Domains - Verification
- Domain People - Contacts & Profiles
- Domain Shared Contacts - Global Address List
- Email Audit Monitor
- Find File Owner
- Google Data Transfers
- Groups
- Groups - Membership
- Inbound SSO
- Licenses
- Mobile Devices
- Organizational Units
- Reports
- Reseller
- Resources
- Send Email
- Schemas
- Shared Drives
- Sites
- Users
- Unmanaged Accounts
- Users - Signout and Turn off 2-Step Verification
- Vault - Takeout
- Version and Help
Special Service Account Access
Service Account Access
- Users - Application Specific Passwords
- Users - Backup Verification Codes
- Users - Calendars
- Users - Calendars - Access
- Users - Calendars - Events
- Users - Classroom - Profile
- Users - Deprovision
- Users - Contacts
- Users - Contacts - Delegates
- Users - Data Studio
- Users - Drive - File Selection
- Users - Drive - Activity/Settings
- Users - Drive - Cleanup
- Users - Drive - Copy/Move
- Users - Drive - Files-Display
- Users - Drive - Files-Manage
- Users - Drive - Labels
- Users - Drive - Orphans
- Users - Drive - Ownership
- Users - Drive - Permissions
- Users - Drive - Revisions
- Users - Drive - Shortcuts
- Users - Drive - Transfer
- Users - Forms
- Users - Gmail - Delegates
- Users - Gmail - Filters
- Users - Gmail - Forwarding
- Users - Gmail - Labels
- Users - Gmail - Messages/Threads
- Users - Gmail - Profile
- Users - Gmail - S/MIME
- Users - Gmail - SendAs/Signature/Vacation
- Users - Gmail - Settings
- Users - Group Membership
- Users - Keep
- Users - People - Contacts & Profiles
- Users - Photo
- Users - Profile Sharing
- Users - Shared Drives
- Users - Spreadsheets
- Users - Tasks
- Users - Tokens