-
Notifications
You must be signed in to change notification settings - Fork 473
Cloud Identity Devices
- API documentation
- Query documentation
- Definitions
- Create a company device
- Delete devices
- Wipe devices
- Perform device actions
- Synchronize devices
- Display devices
- Print devices
- Display device counts
- Approve or block device users
- Delete device users
- Wipe device users
- Perform device user actions
- Display device users
- Display device user counts
- Print device users
- Display device user client state
- Update device user client state
- https://cloud.google.com/identity/docs/reference/rest/v1/devices
- https://cloud.google.com/identity/docs/reference/rest/v1/devices.deviceUsers
- https://cloud.google.com/identity/docs/reference/rest/v1/devices.deviceUsers.clientStates
- https://cloud.google.com/endpoint-verification/docs/overview
- https://developers.google.com/admin-sdk/directory/v1/search-operators
- https://support.google.com/a/answer/7549103
<AssetTag> ::= <String>
<AssetTagList> ::= "<AssetTag>(,<AssetTag>)*"
<QueryDevice> ::= <String>
See: https://support.google.com/a/answer/7549103
<QueryDeviceList> ::= "<QueryDevice>(,<QueryDevice>)*"
<DeviceID> ::= devices/<String>
<DeviceIDList> ::= "<DeviceID>(,<DeviceID>)*"
<DeviceEntity> ::=
<DeviceIDList> | devicesn <String> |
(query:<QueryDevice>)|(query <QueryDevice>)
<DeviceType> ::= android|chrome_os|google_sync|linux|mac_os|windows
<DeviceUserID> ::= devices/<String>/deviceUsers/<String>
<DeviceUserEntity> ::=
<DeviceUserIDList> |
(query:<QueryDevice>)|(query <QueryDevice>)
<DeviceFieldName> ::=
androidspecificattributes|
assettag|
basebandversion|
bootloaderversion|
brand|
buildnumber|
compromisedstate|
createtime|
devicetype|
enableddeveloperoptions|
enabledusbdebugging|
endpointverificationspecificattributes|
encryptionstate|
imei|
kernelversion|
lastsynctime|
managementstate|
manufacturer|
meid|
model|
name|
networkoperator|
osversion|
otheraccounts|
ownertype|
releaseversion|
securitypatchtime|
serialnumber|
wifimacaddresses
<DeviceFieldNameList> ::= "<DeviceFieldName>(,<DeviceFieldName>)*"
<DeviceAction> ::=
cancelwipe|
wipe
<DeviceUserFieldName> ::=
compromisedstate|
createtime|
firstsynctime|
languagecode|
lastsynctime|
managementstate|
name|
passwordstate|
useragent|
useremail
<DeviceUserFieldNameList> ::= "<DeviceUserFieldName>(,<DeviceUserFieldName>)*"
<DeviceOrderbyFieldName> ::=
createtime|devicetype|lastsynctime|model|osversion|serialnumber
<DeviceUserAction> ::=
approve|
block|
cancelwipe|
wipe
Adds a new device to the Google company-owned inventory. Once a user is assigned and enrolled on the device the device will be considered company-owned for management purposes. The device will also register as company-owned with Google services like Context-Aware Access (CAA).
gam create device serialnumber <String> devicetype <DeviceType> [assettag <String>]
Arguments serialnumber <String>
and devicetype <DeviceType>
are required; you can optionally specify assettag <String>
.
Delete a device from appearing in the Admin console, stop syncing for the device user. No user data should be removed.
gam delete device <DeviceEntity> [doit]
If <DeviceEntity>
uses a query, the doit
option must be used to enable execution.
Wiping a device performs a factory reset, all device data is removed.
gam cancelwipe device <DeviceEntity> [doit]
gam wipe device <DeviceEntity> [removeresetlock] [doit]
If <DeviceEntity>
uses a query, the doit
option must be used to enable execution.
Specifying removeresetlock
will remove the account lock on the Android or iOS device.
This lock is enabled by default and requires the existing device user to log in after the wipe in order to unlock the device.
This is an alternative form of the above commands
gam update device <DeviceEntity> action <DeviceAction> [removeresetlock] [doit]
If <DeviceEntity>
uses a query, the doit
option must be used to enable execution.
Specifying removeresetlock
when <DeviceAction>
is wipe
will remove the account lock on the Android or iOS device.
This lock is enabled by default and requires the existing device user to log in after the wipe in order to unlock the device.
This command generates a list of your current company devices, either a complete list or a subset based on a query. A CSV file is read to generate another list of devices.
At a minimum, two values are required for devices in the CSV file list; a device type and a serial number. For the device type, you can either specify a static device type or specify the column in the CSV file that contains a device type.
-
static_devicetype <DeviceType>
- A fixed device type -
devicetype_column <String>
- The name of the column containing device types; if not specified,deviceType
is used
For the serial number, you must specify the column in the CSV file that contains a serial number.
-
serialnumber_column <String>
- The name of the column containing serial numbers; if not specified,serialNumber
is used
You can optionally specify the column in the CSV file that contains an asset tag.
-
assettag_column <String>
- The name of the column containing asset tags; the typical value isassetTag
These two/three columns are used to match current company devices against the CSV file devices.
- Devices in the CSV device list will be created if they are not the the current company device list.
- Devices in the current company device list that are not in the CSV device list will have an optional operation performed on them.
-
unassigned_missing_action delete|wipe|none
- Perform this operation if the company device has never been assigned; default action isdelete
-
assigned_missing_action delete|wipe|none
- Perform this operation if the company device has been assigned; default action isnone
-
If preview
is specified, the operations that would be performed are previewed but are not performed; use this to test.
gam sync devices
[(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime<String> <Time>)*]
csvfile <FileName>
(devicetype_column <String>)|(static_devicetype <DeviceType>)
(serialnumber_column <String>)
[assettag_column <String>]
[unassigned_missing_action delete|wipe|none]
[assigned_missing_action delete|wipe|none]
[preview]
gam info device <DeviceEntity>
<DeviceFieldName>* [fields <DeviceFieldNameList>] [userfields <DeviceUserFieldNameList>]
[nodeviceusers]
[formatjson]
By default, Gam displays the information as an indented list of keys and values.
-
formatjson
- Display the fields in JSON format.
gam print devices [todrive <ToDriveAttribute>*]
[(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime<String> <Time>)*]
<DeviceFieldName>* [fields <DeviceFieldNameList>] [userfields <DeviceUserFieldNameList>]
[orderby <DeviceOrderByFieldName> [ascending|descending]]
[all|company|personal|nocompanydevices|nopersonaldevices]
[nodeviceusers]
[formatjson [quotechar <Character>]]
By default, all devices are displayed; use the query options to limit the display.
To AND query terms, put all of your terms in one query:
gam print devices query "manufacturer:Meizu os:Android 7.0.0"
To OR query terms, put the terms im multiple queries:
gam print devices queries "'model:iPhone 6','model:samsung'"
Select the view of devices to display:
-
all
- Company and personal devices; this is the default -
company|nopersonaldevices
- Company devices -
personal|nocompanydevices
- Personal devices
By default, Gam makes additional API calls to display the device users for the devices;
use nodeviceuser
to suppress making the additional calls.
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 <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.
Display the number of devices.
gam print devices
[(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime<String> <Time>)*]
[all|company|personal|nocompanydevices|nopersonaldevices]
showitemcountonly
Example
$ gam print devices queries "'model:Mac'" showitemcountonly
Getting all Devices that match query (model:Mac), may take some time on a large Google Workspace Account...
Got 100 Devices...
Got 200 Devices...
Got 300 Devices...
...
Got 900 Devices...
Got 995 Devices...
Got 995 Devices...
995
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 print devices queries "'model:Mac'" showitemcountonly)
Windows PowerShell
count = & gam print devices queries "'model:Mac'" showitemcountonly
Approve or block user profiles on a device.
gam approve deviceuser <DeviceUserEntity> [doit]
gam block deviceuser <DeviceUserEntity> [doit]
If <DeviceUserEntity>
uses a query, the doit
option must be used to enable execution.
Delete a device user from appearing in the Admin console, stop syncing for the device user. No user data should be removed.
gam delete deviceuser <DeviceUserEntity> [doit]
If <DeviceUserEntity>
uses a query, the doit
option must be used to enable execution.
Wipe a device user profile from a device. In the case of Android for Work, the work profile will be removed but the personal profile left alone.
gam wipe deviceuser <DeviceUserEntity> [doit]
gam cancelwipe deviceuser <DeviceUserEntity> [doit]
If <DeviceUserEntity>
uses a query, the doit
option must be used to enable execution.
This is an alternative form of the above commands.
gam update deviceuser <DeviceUserEntity> action <DeviceUserAction> [doit]
If <DeviceUserEntity>
uses a query, the doit
option must be used to enable execution.
gam info deviceuser <DeviceUserEntity>
<DeviceUserFieldName>* [fields <DeviceUserFieldNameList>]
[formatjson]
gam print deviceusers [todrive <ToDriveAttribute>*]
[select <DeviceID>]
[(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime<String> <Time>)*]
<DeviceUserFieldName>* [fields <DeviceUserFieldNameList>]
[orderby <DeviceOrderByFieldName> [ascending|descending]]
[formatjson [quotechar <Character>]]
By default, Gam displays device users for all devices;
-
select <DeviceID>
- Display users for a specific device -
(query <QueryDevice>)|(queries <QueryDeviceList>)
- Display users that match queries.
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 <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.
Display the number of device users.
gam print deviceusers [todrive <ToDriveAttribute>*]
[select <DeviceID>]
[(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime<String> <Time>)*]
showitemcountonly
Example
$ gam print deviceusers queries "'model:Mac'" showitemcountonly
Getting all Device Users that match query (model:Mac), may take some time on a large Google Workspace Account...
Got 20 Device Users...
Got 40 Device Users...
Got 60 Device Users...
...
Got 980 Device Users...
Got 995 Device Users...
Got 995 Device Users...
995
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 print deviceusers queries "'model:Mac'" showitemcountonly)
Windows PowerShell
count = & gam print deviceusers queries "'model:Mac'" showitemcountonly
gam info deviceuserstate <DeviceUserEntity> [clientid <String>]
The API that supports this command is in beta mode. In particular, setting assettags
and customvalues
works if you set the values once; each additional time you set values they are added to the existing values
and they is no way at the moment to clear values.
gam update deviceuserstate <DeviceUserEntity> [clientid <String>]
[customid <String>] [assettags clear|<AssetTagList>]
[compliantstate|compliancestate compliant|noncompliant] [managedstate clear|managed|unmanaged]
[healthscore very_poor|poor|neutral|good|very_good] [scorereason clear|<String>]
(customvalue (bool|boolean <Boolean>)|(number <Integer>)|(string <String>))*
Need more help? Ask on the GAM Discussion Group
Update History
Installation
- How to Install GAM7
- How to Upgrade GAMADV-XTD3 to GAM7
- How to Upgrade Legacy GAM to GAM7
- How to Update GAM7
- Install GAM as Python Library
- GAM7 on Chrome OS Devices
- GAM7 on Android Devices
- Google Network Addresses
- HTTPS Proxy
- SSL Root CA Certificates
- How to Uninstall GAM7
Configuration
- Authorization
- GAM Configuration
- Running GAM7 securely on a Google Compute Engine
- Using GAM7 with a delegated admin service account
- Using GAM7 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
Definitions
Command Processing
- Bulk Processing
- Command Line Parsing
- Command Logging and Progress
- Command data from Google Docs/Sheets/Storage
- CSV Special Characters
- 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
- 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
- Cloud Identity Policies
- Cloud Storage
- 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 - Analytics Admin
- Users - Application Specific Passwords
- Users - Backup Verification Codes
- Users - Calendars
- Users - Calendars - Access
- Users - Calendars - Events
- Users - Chat
- Users - Classification Labels
- Users - Classroom - Profile
- Users - Deprovision
- Users - Contacts
- Users - Contacts - Delegates
- Users - Drive - File Selection
- Users - Drive - Activity/Settings
- Users - Drive - Cleanup
- Users - Drive - Comments
- Users - Drive - Copy/Move
- Users - Drive - Files-Display
- Users - Drive - Files-Manage
- Users - Drive - Orphans
- Users - Drive - Ownership
- Users - Drive - Permissions
- Users - Drive - Query
- Users - Drive - Revisions
- Users - Drive - Shortcuts
- Users - Drive - Transfer
- Users - Forms
- Users - Gmail - Client Side Encryption
- 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 - Looker Studio
- Users - Meet
- Users - Classroom - Profile
- Users - People - Contacts & Profiles
- Users - Photo
- Users - Profile Sharing
- Users - Shared Drives
- Users - Spreadsheets
- Users - Tasks
- Users - Tokens
- Users - YouTube
GAM Tutorials
- Managing Users, Groups, Aliases, Domains, Mobile and Chrome Devices, and Resource Calendars
- Group Settings
- Data Transfers
- Print Users, Groups, Aliases, Mobile and Chrome OS devices, OUs, Licenses and Reports
- Managing Custom User Schemas
- User Email Settings
- User Security Settings
- Managing Classroom
- Managing Devices
- Chrome Policy Settings
- Chrome Browser Management
- Calendar Settings
- Unmanaged Users and Invitations
- Google Drive Management
- Inbound SSO Settings
- Managing Admins
- Domain Verification
- Printers