- ChromeOS Devices
- https://developers.google.com/admin-sdk/directory/v1/reference/chromeosdevices
- https://support.google.com/chrome/a/answer/1698333
<OrgUnitPath> ::= /|(/<String)+
<QueryCrOS> ::= <String> See: https://support.google.com/chrome/a/answer/1698333
<CrOSID> ::= <String>
<CrOSIDList> ::= "<CrOSID>(,<CrOSID>)*"
<SerialNumber> ::= <String>
<SerialNumberList> ::= "<SerialNumber>(,<SerialNumber>)*"
<CrOSEntity> ::=
<CrOSIDList> | (cros_sn <SerialNumberList>) |
(query:<QueryCrOS>)|(query:orgunitpath:<OrgUnitPath>)|(query <QueryCrOS>) |
<FileSelector> | <CSVFileSelector> | <CSVkmdSelector>
<CrOSAttribute> ::=
(asset|assetid|tag <String>)|
(location <String>)|
(notes <String>)|(updatenotes <String>)|
(org|ou <OrgUnitPath>)|
(user <Name>)
<CrOSFieldName> ::=
activetimeranges|timeranges|
annotatedassetid|assetid|asset|
annotatedlocation|location|
annotateduser|user|
autoupdateexpiration|
bootmode|
cpustatusreports|
devicefiles|
deviceid|
diskvolumereports|
dockmacaddress|
ethernetmacaddress|
ethernetmacaddress0|
firmwareversion|
lastenrollmenttime|
lastsync|
macaddress|
manufacturedate|
meid|
model|
notes|
ordernumber|
orgunitpath|org|ou|
osversion|
platformversion|
recentusers|
serialnumber|
status|
supportenddate|
systemramtotal|
systemramfreereports|
tpmversioninfo|
willautorenew
<CrOSFieldNameList> ::= "<CrOSFieldName>(,<CrOSFieldName>)*"
<CrOSListFieldName> ::=
activetimeranges|timeranges|
cpustatusreports|
devicefiles|
diskvolumereports|
recentusers|
systemramfreereports
<CrOSOrderByFieldName> ::=
lastsync|location|notes|serialnumber|status|supportenddate|user
<CrOSAction> ::=
deprovision_same_model_replace|
deprovision_different_model_replace|
deprovision_retiring_device|
disable|
reenable
gam update cros <CrOSEntity> <CrOSAttribute>+ [quickcrosmove [<Boolean>]]
gam <CrOSTypeEntity> update <CrOSAttribute>+ [quickcrosmove [<Boolean>]]
Google has introduced a new, faster method for moving CrOS devices to a new OU. The quickcrosmove
option controls which method Gam uses.
quickcrosmove not specified
- use individual methodquickcrosmove False
- use individual methodquickcrosmove True
- use new methodquickcrosmove
- use new method
If quickcrosmove
is False or the OU is not being updated, the individual method is used to update all attributes.
If quickcrosmove
is True and the OU is the only <CrOSAttribute>
being updated, the new method is used.
If quickcrosmove
is True and other <CrOSAttribute>
are being updated in addition to the OU, the new method is used
to update the OU and the individual method is used to update the other <CrOSAttribute>
.
With either the individual or new method, batches of devices are processed to minimize the number of API calls.
The batch_size
value from gam.cfg controls the number of deviceIds handled in each batch by either method.
In the new method, Google doesn't seem to do any error checking of the CrOS deviceIds, there is no error message given if invalid CrOS deviceIds are specified.
gam cros_ou /Students/2017 update ou /Students/2018 quickcrosmove
If you specify the updatenotes <String>
option and it contains the string #notes#
, the existing notes value will replace #notes#
.
This requires an additional API to get the existing value.
If you have a CSV file, UpdateCrOS.csv with two columns: deviceId,notes this command will add a new line of notes to the front of the existing notes:
gam csv UpdateCrOS.csv gam update cros ~deviceId updatenotes "~~notes~~\n#notes#"
gam update cros <CrOSEntity> action <CrOSAction> [acknowledge_device_touch_requirement]
gam <CrOSTypeEntity> update action <CrOSAction> [acknowledge_device_touch_requirement]
As deprovisioning ChromeOS devices in not reversible, you must enter acknowledge_device_touch_requirement
when <CrOSAction>
is deprovision_same_model_replace
, deprovision_different_model_replace
or
deprovision_retiring_device
.
gam info cros <CrOSEntity> [guessaue] [nolists] [listlimit <Number>] [start <Date>] [end <Date>]
[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
[downloadfile latest|<Time>] [targetfolder <FilePath>] [formatjson]
gam <CrOSTypeEntity> info [guessaue] [nolists] [listlimit <Number>] [start <Date>] [end <Date>]
[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
[downloadfile latest|<Time>] [targetfolder <FilePath>] [formatjson]
By default, Gam displays the information as an indented list of keys and values:
formatjson
- Display the fields in JSON format.
gam info cros <CrOSEntity> [downloadfile latest|<Time>] [targetfolder <FilePath>]
gam <CrOSTypeEntity> info [downloadfile latest|<Time>] [targetfolder <FilePath>]
Select the device file to download by its timestamp.
downloadfile latest
- Download the device file with the most recent timestamp.downloadfile <Time>
- Download the device file with the<
Time>` timestamp.
By default, when getting a device file, it is downloaded to the directory specified in gam.cfg/drive_dir
.
targetfolder <FilePath>
- Specify an alternate location for the downloaded file.
Suppuse that you have an OU "/Kiosk Chromebooks" that contains ChromeOS devices running in kiosk mode and you want to download their device files.
Get the list of device files.
gam redirect csv ./CrOSDeviceFiles.csv cros_ou "/Kiosk ChromeBooks" print cros fields deviceId,devicefiles
Download the device files serially.
gam redirect stdout ./CrOSDeviceFiles.out redirect stderr stdout csvkmd cros ./CrOSDeviceFiles.csv keyfield deviceId matchfield deviceFiles.type LOG_FILE datafield deviceFiles.createTime get devicefile select csvdata deviceFiles.createTime
Download the device files in parallel.
gam redirect stdout ./CrOSDeviceFiles.out multiprocess redirect stderr stdout csv ./CrOSDeviceFiles.csv matchfield deviceFiles.type LOG_FILE gam cros ~deviceId get devicefile select ~deviceFiles.createTime
Suppose you want only the last device file for each Chromebook.
Download the device files serially.
gam redirect stdout ./CrOSDeviceFiles.out redirect stderr stdout cros_ou "/Kiosk ChromeBooks" get devicefile select last 1
Download the device files in parallel
gam config auto_batch_min 1 redirect stdout ./CrOSDeviceFiles.out multiprocess redirect stderr stdout cros_ou "/Kiosk ChromeBooks" get devicefile select last 1
gam <CrOSTypeEntity> print
gam <CrOSTypeEntity> print cros
gam print cros [todrive <ToDriveAttribute>*]
[(query <QueryCrOS>)|(queries <QueryCrOSList>)] [limittoou <OrgUnitItem>]
(querytime.* <Time>)* [guessaue]
[orderby <CrOSOrderByFieldName> [ascending|descending]]
[nolists|(<CrOSListFieldName>* [onerow]) [listlimit <Number>] [start <Date>] [end <Date>]
[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
[sortheaders] [formatjson] [quotechar <Character>]
Use these options to select CrOS devices; if none are chosen, all CrOS devices in the account are selected:
(query <QueryCrOS>)|(queries <QueryCrOSList>)
- Limit CrOS devices to those that match a querylimittoou <OrgUnitItem>
- Limit CrOS devices to those directly in the OU<OrgUnitItem>
Use the querytime.* <Time>
option to allow times, usually relative, to be substituted into the query <QueryCrOS>
and queries <QueryCrOSList>
options.
The querytime.* <Time>
value replaces the string #querytime.*#
in any queries.
The characters following querytime
can be any combination of lowercase letters and numbers.
gam print cros [todrive <ToDriveAttribute>*] select <CrOSTypeEntity>
[guessaue]
[orderby <CrOSOrderByFieldName> [ascending|descending]]
[nolists|(<CrOSListFieldName>* [onerow]) [listlimit <Number>] [start <Date>] [end <Date>]
[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
[sortheaders] [formatjson] [quotechar <Character>]
gam <CrOSTypeEntity> print cros [todrive <ToDriveAttribute>*]
[guessaue]
[orderby <CrOSOrderByFieldName> [ascending|descending]]
[nolists|(<CrOSListFieldName>* [onerow])] [listlimit <Number>] [start <Date>] [end <Date>]
[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
[sortheaders] [formatjson] [quotechar <Character>]
The first column will always be deviceId; the remaining field names will be sorted if allfields
, basic
, full
or sortheders
is specified;
otherwise, the remaining field names will appear in the order specified.
-
basic
- Output these column headers: deviceId,annotatedAssetId,annotatedLocation,annotatedUser,lastSync,notes,serialNumber,status -
allfields/full
- Output all column headers including six list headers: activeTimeRanges, cpuStatusReports, deviceFiles, diskVolumeReports, recentUsers and systemRamFreeReports that repeat with multiple subvalues each, yielding a large number of columns that make the output hard to process. -
nolists
- Suppresses these six headers; if you want these headers in a more manageable form use the following arguments. -
<CrOSListFieldName>
- By default, one set of values for all<CrOSListFieldName>
fields specified will be output on a separate row with all of the other headers. -
onerow
- Output all of the<CrOSListFieldName>
on a single row -
listlimit <Number>
- Limits the number of repetitions to<Number>
; if not specified or<Number>
equals zero, there is no limit. -
start <Date>
andend <Date>
- Constrain activeTimeRanges, cpuStatusReports, deviceFiles and systemRamFreeReports to fall within the specified<Dates>
. If a<Date>
isn't specified, there is no filtering in that range. -
guessaue
- Output columnsguessedAUEDate
andguessedAUEModel
that indicate the Auto Update Expiration information for the device. You should comparemodel
andguessedAUEModel
to verify that the proper date has been determined.- See: https://support.google.com/chrome/a/answer/6220366
- Google recently (2019-08) added a field,
autoUpdateExpiration
, that shows the Auto Update Expiration date.
By default, Gam displays the information as columns of fields; the following option causes the ouput 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
.
Print information about CrOS devices synced more than 30 days ago:
gam print cros query "sync:..#querytime1#" querytime1 -30d
Print information about CrOS devices synced in the last 30 days:
gam print cros query "sync:#querytime1#.." querytime1 -30d
Print information about CrOS devices synced between 45 days ago and 30 days ago:
gam print cros query "sync:#querytime1#..#querytime2#" querytime1 -45d querytime2 -30d
gam print crosactivity [todrive <ToDriveAttribute>*]
[(query <QueryCrOS>)|(queries <QueryCrOSList>)] [limittoou <OrgUnitItem>]
(querytime.* <Time>)*
[orderby <CrOSOrderByFieldName> [ascending|descending]] [recentusers] [timeranges] [both] [devicefiles] [all] [listlimit <Number>] [start <Date>] [end <Date>]
[delimiter <Character>] [formatjson] [quotechar <Character>]
Use these options to select CrOS devices; if none are chosen, all CrOS devices in the account are selected:
(query <QueryCrOS>)|(queries <QueryCrOSList>)
- Limit CrOS devices to those that match a querylimittoou <OrgUnitItem>
- Limit CrOS devices to those directly in the OU<OrgUnitItem>
Use the querytime.* <Time>
option to allow times, usually relative, to be substituted into the query <QueryCrOS>
and queries <QueryCrOSList>
options.
The querytime.* <Time>
value replaces the string #querytime.*#
in any queries.
The characters following filtertime
can be any combination of lowercase letters and numbers.
gam print crosactivity [todrive <ToDriveAttribute>*] select <CroSTypeEntity>
[orderby <CrOSOrderByFieldName> [ascending|descending]] [recentusers] [timeranges] [both] [devicefiles] [all]
[listlimit <Number>] [start <Date>] [end <Date>]
[delimiter <Character>] [formatjson] [quotechar <Character>]
gam <CroSTypeEntity> print crosactivity [todrive <ToDriveAttribute>*]
[orderby <CrOSOrderByFieldName> [ascending|descending]] [recentusers] [timeranges] [both] [devicefiles] [all]
[listlimit <Number>] [start <Date>] [end <Date>]
[delimiter <Character>] [formatjson] [quotechar <Character>]
-
The basic column headers are: deviceId,annotatedAssetId,annotatedLocation,serialNumber,orgUnitPath.
-
recentusers
- All of the recent users email addresses, separated by the delimiter<Character>
, with header recentUsers.email, are output with the basic headers. -
The delimiter defaults to
gam.cfg/csv_output_field_delimiter
. -
timeranges
- For each time range entry, activeTimeRanges.date, activeTimeRanges.duration and activeTimeRanges.minutes are output on a separate row with the basic headers. -
devicefiles
- For each device file, the columns deviceFiles.type and deviceFiles.createTime are output on a separate row with the basic headers. -
both
- Specifiesrecentusers
andtimeranges
. -
all
- Specifiesrecentusers
,timeranges
anddevicefiles
. -
The default is to include both
recentusers
andtimeranges
. -
listlimit <Number>
- Limits the number of repetitions to<Number>
; if not specified or<Number>
equals zero, there is no limit. -
start <Date>
andend <Date>
- Filter the time ranges and device files to fall with in the specified<Dates>
. If a<Date>
isn't specified, there is no filtering in that range.
By default, Gam displays the information as columns of fields; the following option causes the ouput 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
.
To search within a specific field only (for example, to search for a specific user), you can enter an operator followed by an argument -- for example, user:jsmith
. You can use single words or quoted lists of words as an argument when running an operator query.
To run an operator query, follow these guidelines for each field:
Serial Number:
Enter id:
as the operator. For example, if you are searching for the serial number 12345abcdefg, enter the following:
gam print cros query "id:12345abcdefg"
Partial serial number searches are supported, as long as you enter at least three characters in the serial number.
Status: To view all provisioned or deprovisioned devices, select the status from the left drop-down, and all of the devices that fit this criterion will appear in the view. Alternatively, you can do the following searches from the All devices view:
gam print cros query "status:[provisioned|disable|deprovisioned]"
User: Enter user: as the operator. For example, to match the name Joe, but not Joey, enter the following:
gam print cros query "user:joe"
To match the name Tom Sawyer or A. Tom Sawyer, but not Tom A. Sawyer, enter with quotation marks:
gam print cros query "user:'tom sawyer'"
Location Enter location: as the operator. For example, to match Seattle, enter the following:
gam print cros query "location:seattle"
Notes Enter note: as the operator. For example, to match loaned from John, enter the following with quotation marks:
gam print cros query "note:'loaned from john'"
Register This field is not displayed on the Chrome OS settings page. However, you can search for devices that were registered on a given date, or within a given time range.
Enter register: as the operator, and enter a date and time (or time range) as the argument. For example, to search for all devices registered on March 23, 2013, enter the following:
gam print cros query "register:2013-03-23"
For additional examples using dates, times, and ranges, see "Format for date and time searches" below.
Last Sync Enter sync: as the operator and a date or time range as the argument. For example, to search for all devices that were last synced with policy settings on October 12, 2013, enter the following:
gam print cros query "sync:2013-10-12"
For additional examples using dates, times, and ranges, see "Format for date and time searches" below.
Asset ID
Enter asset_id: as the operator. For example, to match the partial Asset ID 1234, enter the following:
gam print cros query "asset_id:1234"
WiFi MAC Address
Enter wifi_mac: as the operator. Address should be entered without spaces or colons. Partial address matching is not supported. Be aware that multiple devices may report the same address to the Admin console, and more than one result may be returned. For example, to search for the device(s) with WiFi MAC 6C:29:95:72:4C:50, enter the following:
gam print cros query "wifi_mac:6c2995724c50"
Ethernet MAC Address
Enter ethernet_mac: as the operator. Address should be entered without spaces or colons. Partial address matching is not supported. Be aware that multiple devices may report the same address to the Admin console, and more than one result may be returned. For example, to search for the device(s) with ethernet MAC E8:EA:6A:15:79:81, enter the following:
gam print cros query "ethernet_mac:e8ea6a157981"