# Users - Shared Drives - [API documentation](#api-documentation) - [Query documentation](#query-documentation) - [Definitions](#definitions) - [API GUI permission name mapping](#api-gui-permission-name-mapping) - [API GUI restriction name mapping](#api-gui-restriction-name-mapping) - [Display Shared Drive themes](#display-shared-drive-themes) - [Manage Shared Drives](#manage-shared-drives) - [Create a Shared Drive](#create-a-shared-drive) - [Bulk Create Shared Drives](#bulk-create-shared-drives) - [Update Shared Drive settings](#update-shared-drive-settings) - [Delete a Shared Drive](#delete-a-shared-drive) - [Change Shared Drive visibility](#change-shared-drive-visibility) - [Display Shared Drives](#display-shared-drives) - [Display Shared Drive Counts](#display-shared-drive-counts) - [Display Shared Drive Organizers](#display-shared-drive-organizers) - [Manage Shared Drive access](#manage-shared-drive-access) - [Transfer Shared Drive access](#transfer-shared-drive-access) - [Display Shared Drive access](#display-shared-drive-access) - [Display Shared Drive access for specific Shared Drives](#display-shared-drive-access-for-specific-shared-drives) - [Display Shared Drive access for selected Shared Drives](#display-shared-drive-access-for-selected-shared-drives) - [Change single User1 Shared Drive access to User2](#change-single-user1-shared-drive-access-to-user2) - [Bulk change User1 Shared Drive access to User2](#bulk-change-user1-shared-drive-access-to-user2) - [Display empty folders on a Shared Drive](#display-empty-folders-on-a-shared-drive) - [Delete empty folders on a Shared Drive](#delete-empty-folders-on-a-shared-drive) - [Empty the trash on a Shared Drive](#empty-the-trash-on-a-shared-drive) - [Commands not applicable to Shared Drives](#commands-not-applicable-to-shared-drives) ## API documentation * [Drive API - Drives](https://developers.google.com/drive/api/reference/rest/v3/drives) * [Drive API - Files](https://developers.google.com/drive/api/reference/rest/v3/files) * [Manage Shared Drives](https://developers.google.com/drive/v3/web/manage-teamdrives#managing_team_drives_for_domain_administrators) * [Move content to Shared Drives](https://support.google.com/a/answer/7374057) * [Shared Drive Limits](https://support.google.com/a/users/answer/7338880) * [Shared Drives in Org Units](https://support.google.com/a/answer/7337635) ## Query documentation * [Shared Drives Search](https://developers.google.com/drive/api/guides/search-shareddrives) ## Definitions * [``](Drive-File-Selection) * [``](Collections-of-Users) ``` ::= "#" ::= asparagus|bluevelvet|bubblegum|cardinal|chocolateicecream|denim|desertsand| earthworm|macaroni|marsorange|mountaingray|mountaingrey|mouse|oldbrickred| pool|purpledino|purplerain|rainysky|seafoam|slimegreen|spearmint| toyeggplant|vernfern|wildstrawberries|yellowcab ::= aliceblue|antiquewhite|aqua|aquamarine|azure|beige|bisque|black|blanchedalmond| blue|blueviolet|brown|burlywood|cadetblue|chartreuse|chocolate|coral| cornflowerblue|cornsilk|crimson|cyan|darkblue|darkcyan|darkgoldenrod|darkgray| darkgrey|darkgreen|darkkhaki|darkmagenta|darkolivegreen|darkorange|darkorchid| darkred|darksalmon|darkseagreen|darkslateblue|darkslategray|darkslategrey| darkturquoise|darkviolet|deeppink|deepskyblue|dimgray|dimgrey|dodgerblue| firebrick|floralwhite|forestgreen|fuchsia|gainsboro|ghostwhite|gold|goldenrod| gray|grey|green|greenyellow|honeydew|hotpink|indianred|indigo|ivory|khaki| lavender|lavenderblush|lawngreen|lemonchiffon|lightblue|lightcoral|lightcyan| lightgoldenrodyellow|lightgray|lightgrey|lightgreen|lightpink|lightsalmon| lightseagreen|lightskyblue|lightslategray|lightslategrey|lightsteelblue| lightyellow|lime|limegreen|linen|magenta|maroon|mediumaquamarine|mediumblue| mediumorchid|mediumpurple|mediumseagreen|mediumslateblue|mediumspringgreen| mediumturquoise|mediumvioletred|midnightblue|mintcream|mistyrose|moccasin| navajowhite|navy|oldlace|olive|olivedrab|orange|orangered|orchid| palegoldenrod|palegreen|paleturquoise|palevioletred|papayawhip|peachpuff| peru|pink|plum|powderblue|purple|red|rosybrown|royalblue|saddlebrown|salmon| sandybrown|seagreen|seashell|sienna|silver|skyblue|slateblue|slategray| slategrey|snow|springgreen|steelblue|tan|teal|thistle|tomato|turquoise|violet| wheat|white|whitesmoke|yellow|yellowgreen ::= | ::= | ``` ``` ::= (( [charset ] )| (gsheet )| (gdoc )| (gcscsv )| (gcsdoc )) [warnifnodata] [columndelimiter ] [noescapechar ] [quotechar ] [endcsv|(fields )] ::= (json [charset ] ) | (json file [charset ]) | ::= user|group ::= "(,)*" ::= id: ::= /|(/)+ ::= | ::= See: https://docs.python.org/3/library/re.html ::= ::= ::= > ``` ``` ::= createddate|createdtime| folder| lastviewedbyme|lastviewedbymedate|lastviewedbymetime|lastviewedbyuser| modifiedbyme|modifiedbymedate|modifiedbymetime|modifiedbyuser| modifieddate|modifiedtime| name| name_natural| quotabytesused|quotaused| recency| sharedwithmedate|sharedwithmetime| starred| title| title_natural| viewedbymedate|viewedbymetime ::= manager|organizer|owner| contentmanager|fileorganizer| contributor|writer|editor| commenter| viewer|reader ::= anyone|domain|group|user ::= anyone|anyonewithlink| user:|group:| domain:|domainwithlink:; ::= anyone|anyonewithlink|id: ::= | ::= "(, ::= "(,)*" ::= | | | | | ::= | | | | | ::= See: https://developers.google.com/workspace/drive/api/guides/search-shareddrives ::= manager|organizer|owner| contentmanager|fileorganizer| contributor|writer|editor| commenter| viewer|reader ::= "(,)*" ::= ::= ::= | (shareddriveid )|(shareddriveid:)| (shareddrive )|(shareddrive:) ::= backgroundimagefile| backgroundimagelink| capabilities| colorrgb| createdtime| id| name| restrictions| themeid ::= "(,)*" ::= (shareddriveid ) | (shareddriveid:) ::= (shareddrive ) | (shareddrive:) ::= (shareddrivefilename ) | (shareddrivefilename:) ::= (shareddrivequery ) | (shareddrivequery:) ::= all_files | all_folders | all_google_files | all_non_google_files | all_items ::= [] | [] | | | | | ) | ) ::= adminmanagedrestrictions| allowcontentmanagerstosharefolders| copyrequireswriterpermission| domainusersonly| downloadrestrictedforreaders|downloadrestrictions.restrictedforreaders| downloadrestrictedforwriters|downloadrestrictions.restrictedforwriters| drivemembersonly|teammembersonly| sharingfoldersrequiresorganizerpermission ``` ## API GUI permission name mapping | API setting | GUI setting | |-------------|-------------| | organizer | Manager | | fileOrganizer | Content manager | | writer | Contributor | | commenter | Commenter | | reader | Viewer | ## API GUI restriction name mapping | API Setting | Description | |-------------|-------------| | adminManagedRestrictions | Whether administrative privileges on this shared drive are required to modify restrictions. | | domainUsersOnly | Whether access to this shared drive and items inside this shared drive is restricted to users of the domain to which this shared drive belongs. | | driveMembersOnly | Whether access to items inside this shared drive is restricted to its members. | | allowContentManagersToShareFolders (GAM defined) | If true, users with either the organizer role or the file organizer role can share folders. If false, only users with the organizer role can share folders. | | sharingFoldersRequiresOrganizerPermission | If true, only users with the organizer role can share folders. If false, users with either the organizer role or the file organizer role can share folders. | | copyRequiresWriterPermission | Whether the options to copy, print, or download files inside this shared drive, should be disabled for readers and commenters. | | downloadRestrictions.restrictedForWriters | Whether download and copy is restricted for writers. If true, download is also restricted for readers. | | downloadRestrictions.restrictedForReaders | Whether download and copy is restricted for readers. | | API Setting | False | True | GUI Setting | Checked | Unchecked | |-------------|-------|------|-------------|---------|-----------| | adminManagedRestrictions | X | | Shared drive settings can be modified | | | | adminManagedRestrictions | | X | Shared drive settings can **not** be modified | | | | | | | **Access** | | domainUsersOnly | X | | Allow people outside of Domain name to access files | X | | | domainUsersOnly | | X | Allow people outside of Domain name to access files | | X | | driveMembersOnly | X | | Allow people who aren't shared drive members to access files | X | | | driveMembersOnly | | X | Allow people who aren't shared drive members to access files | | X | | | | | **Role permissions** | | allowContentManagersToShareFolders | X | | Allow content managers to share folders | | X | | allowContentManagersToShareFolders | | X | Allow content managers to share folders | X | | | sharingFoldersRequiresOrganizerPermission | X | | Allow content managers to share folders | X | | | sharingFoldersRequiresOrganizerPermission | | X | Allow content managers to share folders | | X | | | | | **People who can download, copy, and print** | | downloadRestrictions.restrictedForWriters | X | | Contributors and content managers | X | | | downloadRestrictions.restrictedForWriters | | X | Contributors and content managers | | X | | downloadRestrictions.restrictedForReaders | X | | Commenters and viewers | X | | | downloadRestrictions.restrictedForReaders | | X | Commenters and viewers | | X | ## Display Shared Drive themes ``` gam show shareddrivethemes ``` ## Manage Shared Drives ## Create a Shared Drive The user that creates a Shared Drive is given the permission role organizer for the Shared Drive, ``` gam create shareddrive [(theme|themeid )| ([customtheme ] [color ])] ([restrictions.] )* [hide ] [ou|org|orgunit ] [errorretries ] [updateinitialdelay ] [updateretrydelay ] [(csv [todrive *] (addcsvdata )*) | returnidonly] ``` * `themeid` - a Shared Drive themeId obtained from `show shareddrivethemes` * `customtheme` - set the backgroundImageFile property described here: https://developers.google.com/drive/v3/reference/teamdrives * `` - X coordinate, typically 0.0 * `` - Y coordinate, typically 0.0 * `` - width, typically 1.0 * `color` - set the Shared Drive color * `[restrictions.] ` - Set Shared Drive Restrictions * `hide ` - Set Shared Drive visibility If any attributes other than `themeid` are specified, GAM must create the Drive and then update the Drive attributes. Even though the Create API returns success, the Update API fails and reports that the Drive does not exist. * `errorretries ` - Number of create/update error retries; default value 5, range 0-10 * `updateinitialdelay ` - Initial delay after create before update: default value 10, range 0-60 * `updateretrydelay ` - Retry delay when update fails; default value 10, range 0-60 For this reason, GAM waits `updateinitialdelay ` seconds after the create before attempting the update. GAM repeats the update `errorretries ` times waiting `updateretrydelay ` between tries if the Update API continues to fail. This is acceptable when creating a single Shared Drive, for bulk Shared Drive creation see [Bulk Create Shared Drives](#bulk-create-shared-drives). This option is only available when the command is run as an administrator. * `ou|org|orgunit ` - See: https://workspaceupdates.googleblog.com/2022/05/shared-drives-in-organizational-units-open-beta.html By default, the user and Shared Drive name and ID values are displayed on stdout. * `csv [todrive *]` - Write user, Shared Drive name and ID values to a CSV file. * `addcsvdata ` - Add additional columns of data from the command line to the output * `returnidonly` - Display just the ID of the created Shared Drive as output When either of these options is chosen, no infomation about Shared Drive restrictions or hiding will be displayed. To retrieve the Shared Drive ID with `returnidonly`: ``` Linux/MacOS shareddriveId=$(gam user user@domain.com create shareddrive ... returnidonly) Windows PowerShell $shareddriveId = & gam user user@domain.com create shareddrive ... returnidonly Windows Command Prompt for /f "delims=" %a in ('gam user user@domain.com create shareddrive ... returnidonly') do set shareddriveId=%a ``` ## Bulk Create Shared Drives Most Shared Drive attributes can't be applied as part of the create, the Drive must be created and then updated with the desired attributes. As a newly created Drive can't be updated for 30+ seconds; split the operation into two commands: create and update. Make a CSV file SharedDriveNames.csv with at least two columns, User and name. ``` gam redirect csv ./SharedDrivesCreated.csv multiprocess csv SharedDriveNames.csv gam user "~User" create shareddrive "~name" csv ``` This will create a three column CSV file SharedDriveNamesIDs.csv with columns: User,name,id * There will be a row for each Shared Drive. Use the SharedDrivesCreated.csv file to apply the desired options/attributes. ``` gam redirect stdout ./SharedDrivesUpdated.txt multiprocess redirect stderr stdout csv ./SharedDrivesCreated.csv gam user "~User" update shareddrive "~id" [options/attributes as desired] ``` ## Update Shared Drive settings This command is used to set basic Shared Drive settings. ``` gam update shareddrive [adminaccess|asadmin] [name ] [(theme|themeid )| ([customtheme ] [color ])] ([restrictions.] )* [hide|hidden ] [ou|org|orgunit ] ``` * `themeid` - a Shared Drive themeId obtained from `show shareddrivethemes` * `customtheme` - set the backgroundImageFile property described here: https://developers.google.com/drive/v3/reference/teamdrives * `color` - set the Shared Drive color * `[restrictions.] ` - Set Shared Drive Restrictions * `hidden ` - Set Shared Drive visibility This option is only available when the command is run as an administrator. * `ou|org|orgunit ` - See: https://workspaceupdates.googleblog.com/2022/05/shared-drives-in-organizational-units-open-beta.html ## Delete a Shared Drive ``` gam delete shareddrive [allowitemdeletion] [adminaccess|asadmin] ``` By default, deleting a Shared Drive that contains any files/folders will fail. The `allowitemdeletion` option allows a Super Admin to delete a non-empty Shared Drive. This is not reversible, proceed with caution. ## Change Shared Drive visibility ``` gam hide shareddrive gam unhide shareddrive ``` ## Display Shared Drives ``` gam show shareddriveinfo gam info shareddrive [fields ] [guiroles [] [formatjson] gam show shareddriveinfo [fields ] [guiroles [] [formatjson] gam show shareddrives [matchname ] (role|roles )* [fields ] [showwebviewlink text|hyperlink] [guiroles [] [formatjson] ``` By default, Gam displays all Teams Drives accessible by the user. * `matchname ` - Display Shared Drives with names that match a pattern. * `(role|roles )*` - Display Shared Drives where the user has one of the specified roles. Use option `showwebviewlink` to display the web view link for the Shared Drive. * `showwebviewlink text` - Displays `https://drive.google.com/drive/folders/` * `showwebviewlink hyperlink` - Dsiplays `=HYPERLINK("https://drive.google.com/drive/folders/", "")` By default, Gam displays the information as an indented list of keys and values. * `formatjson` - Display the fields in JSON format. ``` gam print shareddrives [todrive *] [matchname ] (role|roles )* [fields ] [showwebviewlink text|hyperlink] [guiroles []] [formatjson [quotechar ]] ``` By default, Gam displays all Teams Drives accessible by the user. * `matchname ` - Display Shared Drives with names that match a pattern. * `(role|roles )*` - Display Shared Drives where the user has one of the specified roles. Use option `showwebviewlink` to display the web view link for the Shared Drive. * `showwebviewlink text` - Displays `https://drive.google.com/drive/folders/` * `showwebviewlink hyperlink` - Dsiplays `=HYPERLINK("https://drive.google.com/drive/folders/", "")` The Google Drive API does not list roles for Shared Drives so GAM generates a role from the capabilities: * `commenter - canComment: True, canEdit: False` * `reader - canComment: False, canEdit: False` * `writer - canEdit: True, canTrashChildren: False` * `fileOrganizer - canTrashChildren: True, canManageMembers: False` * `organizer - canManageMembers: True` By default, the Drive API role names are displayed, use `guiroles` to display the Google Drive GUI role names. ``` API: GUI commenter: Commenter fileOrganizer: Content manager organizer: Manager reader: Viewer writer: Contributor ``` By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format, * `formatjson` - Display the fields in JSON format. 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 ` 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. ## Display Shared Drive Counts Display the number of Shared Drives. ``` gam show|print shareddrives [shareddriveadminquery|query ] [matchname ] [orgunit|org|ou ] showitemcountonly ``` By default, all Shared Drives are counted; use the following options to select a subset of Shared Drives: * `shareddriveadminquery|query ` - Use a query to select Shared Drives * `matchname ` - Retrieve Shared Drives with names that match a pattern. * `orgunit|org|ou ` - Only Shared Drives in the specified Org Unit are selected Example ``` $ gam user user@domain.com print shareddrives showitemcountonly Getting all Shared Drives for user@domain.com Got 4 Shared Drives for user@domain.com ... 4 ``` The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout. To retrieve the count with `showitemcountonly`: ``` Linux/MacOS count=$(gam user user@domain.com print shareddrives ... showitemcountonly) Windows PowerShell $count = & gam user user@domain.com print shareddrives ... showitemcountonly Windows Command Prompt for /f "delims=" %a in ('gam user user@domain.com print shareddrives ... showitemcountonly') do set count=%a ``` ## Display Shared Drive Organizers The following command can be used instead of the `GetTeamDriveOrganizers.py` script. ``` gam print shareddriveorganizers [todrive *] [adminaccess|asadmin] [(shareddriveadminquery|query ) | (shareddrives|teamdrives (|(select |)))] [orgunit|org|ou ] [matchname ] [domainlist ] [includetypes ] [oneorganizer []] [shownorganizerdrives [false|true|only]] [includefileorganizers []] [delimiter ] ``` Options `shareddriveadminquery|query` and `shareddrives|teamdrives` are mutually exclusive. Options `shareddriveadminquery|query` and `orgunit|org|ou` require `adminaccess|asadmin`. By default, organizers for all Shared Drives are displayed; use the following options to select a subset of Shared Drives: * `shareddriveadminquery|query ` - Use a query to select Shared Drives * `shareddrives|teamdrives ` - Select the Shared Drive IDs specified in `` * `shareddrives|teamdrives select |` - Select the Shared Drive IDs specified in `|` * `orgunit|org|ou ` - Only Shared Drives in the specified Org Unit are selected * `matchname ` - Retrieve Shared Drives with names that match a pattern. For multiple organizers: * `delimiter ` - Separate `organizers` entries with ``; the default value is `csv_output_field_delimiter` from `gam.cfg`. The command defaults do not match the script defaults, they are set for the most common use case: * `domainlist` - The workspace primary domain * `includetypes` - user * `oneorganizer` - True * `shownoorganizerdrives` - True * `includefileorganizers` - False To select organizers from any domain, use: `domainlist ""` For example, to get a single user organizer from your domain for all Shared Drives including no organizer drives: ``` gam redirect csv ./ShareddriveOrganizers.csv print shareddriveorganizers ``` ## Manage Shared Drive access These commands must be issued by a user with Shared Drive permission role organizer. ### Process single ACLs. ``` gam add drivefileacl anyone|(user )|(group )|(domain ) (role ) [withlink|(allowfilediscovery|discoverable [])] [expires|expiration