Содержание
Авторизация
Перед использованием всех Chrome Enterprise Core API необходимо включить Admin SDK API (если он ещё не включен) в консоли Google Developers перейдя по этой ссылке и выбрав проект, в котором вы хотите включить API.
После этого вы сможете получить токен доступа к API двумя способами:
- По протоколу OAuth 2.0 с олицетворением при использовании сервисного аккаунта (инструкции приведены в разделе "Авторизация с олицетворением" ниже).
- По трехстороннему протоколу OAuth 2.0 без олицетворения (инструкции по авторизации запросов вы найдете в руководстве по настройке OAuth 2.0).
Для авторизации доступа к Chrome Enterprise Core API необходимы следующие области действия OAuth:
https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly
или
https://www.googleapis.com/auth/admin.directory.device.chromebrowsers
Авторизация с олицетворением
Чтобы выполнить авторизацию с олицетворением, используя сервисный аккаунт:
- Создайте сервисный аккаунт и получите для него необходимые ключи. Ознакомьтесь с инструкциями о том, как это сделать.
- Идентификатор клиента для этого сервисного аккаунта нужно будет авторизовать для областей действия OAuth, приведенных выше. Для этого в консоли администратора выберите Безопасность > Управление API > Настроить делегирование доступа к данным в домене и добавьте нового клиента. Убедитесь, что идентификатор клиента соответствует уникальному идентификатору вашего сервисного аккаунта.
Получив ключи сервисного аккаунта, вы должны будете запросить для него токен доступа OAuth. Это можно сделать с помощью клиентских библиотек API Google на выбранном вами языке.
Запрос токена OAuth также нужно будет выполнить с олицетворением аккаунта администратора вашего домена.
Ниже приведен пример кода для получения токена OAuth с использованием клиентских библиотек Java API.
package takeout.api.credentials;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
public final class ApiRequestHelper {
public static String getAccessToken(
String serviceAccountKeyFilePath, String adminUserToImpersonate, Collection<String> scopes)
throws IOException {
InputStream is = new FileInputStream(serviceAccountKeyFilePath);
GoogleCredential credential =
GoogleCredential.fromStream(is).toBuilder()
.setServiceAccountScopes(scopes)
.setServiceAccountUser(adminUserToImpersonate)
.build();
if (!credential.refreshToken()) {
throw new RuntimeException(
String.format(
"Failed to fetch refresh token for service account defined in '%s' for user '%s' and"
+ " scopes '%s'",
serviceAccountKeyFilePath, adminUserToImpersonate, String.join(",", scopes)));
}
return credential.getAccessToken();
}
public static void printUsage() {
System.out.println(
"Usage: get_access_token <service account key file> <admin user> [<scope,scope>]");
}
public static void main(String[] args) throws Exception {
if (args.length < 2) {
printUsage();
return;
}
String scopes =
"https://www.googleapis.com/auth/admin.directory.device.chromebrowsers";
if (args.length >= 3) {
scopes = args[2];
}
System.out.println(
getAccessToken(args[0], args[1], new ArrayList<String>(Arrays.asList(scopes.split(",")))));
}
private ApiRequestHelper() {}
}
Используя этот пример кода, вы сможете получить токен доступа для вызова API. Например, если путь к файлу ключа имеет вид /home/private_key.json и вы хотите запросить токен от имени аккаунта администратора admin@domain.com, выполните следующую команду:
ApiRequestHelper
/home/private_key.json admin@domain.com
Примечание. Адрес электронной почты администратора не должен совпадать с адресом сервисного аккаунта (выглядит так: <project-name>-<id>@<project-name>.iam.gserviceaccount.com).
Браузер Chrome
Браузеры Chrome, зарегистрированные в Chrome Enterprise Core.
Представление ресурса
Ресурс ChromeBrowser представлен в Directory API следующим шаблоном кода в формате JSON:
{
"kind": "admin#directory#browserdevice",
"deviceId": string,
"osPlatform": string,
"osPlatformVersion": string,
"osArchitecture":string,
"osVersion": string,
"machineName": string,
"annotatedLocation": string,
"annotatedUser": string,
"annotatedAssetId": string,
"annotatedNotes": string,
"lastPolicyFetchTime": dateTime,
"lastRegistrationTime": dateTime,
"lastActivityTime":dateTime,
"lastStatusReportTime":dateTime,
"virtualDeviceId": string,
"serialNumber": string,
"orgUnitPath": string,
"extensionCount":int,
"policyCount": int,
"safeBrowsingClickThroughCount": int,
"lastDeviceUser": string,
"browserVersions": [string],
"lastDeviceUsers":[
"userName": string,
"lastStatusReportTime":dateTime,
]
"machinePolicies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
"browsers": [
"browserVersion": string,
"channel": string,
"lastStatusReportTime": dateTime,
"lastPolicyFetchTime": dateTime,
"executablePath": string,
"installedBrowserVersion": string,
"plugins":[
"name": string,
"description": string,
"fileame" string,
]
"profiles": [
"name": string,
"id": string,
"lastStatusReportTime": dateTime,
"lastPolicyFectchTime": dateTime,
"safeBrowsingWarnings": int,
"safeBrowsingWarningsClickThrough": int,
"chromeSignedinUserEmail": string,
"extensionPolicies": [
"extensionId": string,
"extensionName": string,
"policies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
]
"extensions": [
"extensionId": string,
"version": string,
"permissions": [string],
"name": string,
"description":string,
"appType": string,
"homepageUrl": string,
"installType": string,
"configuredAppPolicy": string,
"disabled": boolean,
"icons": [
"size": int,
"url": string,
]
]
"userPolicies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
"safeBrowsingWarningsResetTime": string
]
}
Вызов API
Как получить список всех устройств с браузером Chrome, назначенных аккаунту
Ограничение: срок действия токена nextPageToken
, возвращаемого в рамках запроса списка, составляет 1 час. Если в вашем запросе указано большое количество устройств с браузером Chrome, срок действия токена вашей страницы может истечь, прежде чем вы получите список всех устройств. Чтобы уменьшить количество устройств, которые будут показаны в результатах запроса, примените к нему фильтр, например по организационному подразделению.
Чтобы получить список устройств с браузером Chrome, назначенных аккаунту, используйте приведенный ниже GET-запрос и включите в него токен доступа, полученный в разделе Авторизация выше. Для удобства восприятия пример кода разделен на строки.
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers?projection={FULL|BASIC}&query={query string}&orderBy={orderBy
category}&sortOrder={ASCENDING|DESCENDING}&pageToken={token for next results
page, if applicable &maxResults=max number of results per page}
- customerId – это уникальный идентификатор клиентского аккаунта Google.
- При олицетворении администратора аккаунта вы также можете использовать строку my_customer, которая содержит customerId вашего аккаунта. Также значение customerId можно получить, запросив данные о пользователе. При этом в параметре пути userKey соответствующего оператора необходимо указать свой адрес электронной почты администратора или уникальный идентификатор администратора.
В приведенной ниже таблице представлены все параметры, которые можно использовать в таком запросе.
Параметр | Тип | Описание |
---|---|---|
maxResults | Целое число | Максимальное число результатов на странице. Значение не должно превышать 100 (задано по умолчанию). |
orderBy | Строка | Свойство устройства с браузером Chrome, по которому будут отсортированы результаты. |
Возможные значения: | ||
"id" – идентификатор устройства, на котором установлен браузер Chrome. | ||
"last_sync" – дата и время, когда устройство с браузером Chrome было в последний раз было зарегистрировано, получило актуальные настройки правил или загрузило отчет. | ||
"machine_name" – имя компьютера, связанного с устройством. | ||
"extension_count" – общее количество расширений, установленных на устройстве с браузером Chrome. | ||
"policy_count" – общее количество правил, заданных на устройстве с браузером Chrome. | ||
"os_version" – ОС устройства, на котором установлен браузер Chrome. | ||
"last_signed_in_user" – имя последнего пользователя, который вошел в аккаунт на устройстве с браузером Chrome. | ||
"annotated_user" – указанный администратором пользователь устройства с браузером Chrome. | ||
"annotated_location" – указанное администратором местоположение устройства с браузером Chrome. | ||
"annotated_asset_id" – указанный администратором идентификатор объекта устройства с браузером Chrome. | ||
"notes" – указанные администратором заметки об устройстве с браузером Chrome. | ||
"browser_version_channel" – последняя версия Chrome, используемая на устройстве. | ||
"org_unit" – организационное подразделение, к которому принадлежит устройство. | ||
"enrollment_date" – дата регистрации устройства. | ||
"save_browsing_clickthrough" – количество кликов в режиме Безопасного просмотра на устройстве. | ||
"platform_major_version" – тип и номер основной версии, например Windows 10. | ||
"last_activity" – дата и время последнего действия на устройстве. | ||
"browser_version_sortable" – самая старая версия браузера, установленная на устройстве. | ||
"os_version_sortable" – тип и текущий номер версии ОС. | ||
orgUnitPath | Строка | Полный путь к организационному подразделению или его уникальный идентификатор. |
groupId | Строка | Полное название ресурса группы (должно выглядеть так: groups/{group}) или ее уникальный идентификатор. |
pageToken | Строка | Параметр pageToken служит для получения следующей страницы результатов запроса. При этом он равен значению nextPageToken из предыдущего ответа. |
projection | Строка | Возвращать только выбранные поля. |
Возможные значения: | ||
"BASIC" – возвращать только основные поля метаданных, то есть те, которые указаны в перечисленных выше столбцах списка браузеров в консоли администратора. | ||
"FULL" – возвращать все поля метаданных (перечислены выше). | ||
query | Строка | Строка поиска, использующая синтаксис, описанный в разделе "Язык запросов для фильтрации данных" ниже. |
sortOrder | Строка | Показывать результаты в порядке возрастания или убывания. Нужно использовать с параметром orderBy. |
Возможные значения: | ||
"ASCENDING" – в порядке возрастания. | ||
"DESCENDING" – в порядке убывания. |
Пример: фильтрация устройств по имени компьютера
В этом примере выполняется поиск определенного имени компьютера с помощью запроса query=machine_name:CLIENT2012. Ответ содержит один ресурс ChromeBrowser, где machineName – это "CLIENT2012".
Запрос JSON
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers?projection=BASIC&query=machine_name:CLIENT2012&orderBy=status
&sortOrder=ASCENDING&maxResults=100
Ответ JSON
При успешном выполнении запроса будет получен код статуса HTTP 200, а вместе с ним – список устройств с браузером Chrome, отвечающих параметрам вашего запроса.
{
"kind": "directory#browserdevices",
"browsers": [
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19505",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-04T00:29:17.484Z",
"lastActivityTime": "2019-11-04T00:29:17.484Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
},
],
"nextPageToken": "abcdefghijkl123"
}
Как получить свойства устройства с браузером Chrome
Чтобы получить свойства устройства с браузером Chrome, используйте приведенный ниже GET-запрос и включите в него токен доступа, полученный в разделе "Авторизация" выше. Для удобства восприятия пример кода разделен на строки.
GET
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/deviceId?projection={FULL|BASIC}
- customerId – это уникальный идентификатор клиентского аккаунта Google.
- При олицетворении администратора аккаунта вы также можете использовать строку my_customer, которая содержит customerId вашего аккаунта. Также значение customerId можно получить, запросив данные о пользователе. При этом в параметре пути userKey соответствующего оператора необходимо указать свой адрес электронной почты администратора или уникальный идентификатор администратора.
- deviceId – это уникальный идентификатор устройства, который можно найти в ответе на запрос списка устройств с браузером Chrome. Описание синтаксиса запроса, а также свойств запросов и ответов можно найти в документации по API.
В приведенной ниже таблице представлены все параметры, которые можно использовать в таком запросе.
Параметр | Тип | Описание |
---|---|---|
deviceId | Строка | Уникальный идентификатор устройства. Идентификаторы устройств можно получить путем вызова метода browsersdevices.list. Примечание. Этот параметр является обязательным. |
projection | Строка | Определяет, содержит ли ответ полный список свойств или только некоторые из них. |
Возможные значения: | ||
"BASIC" – включает только основные поля метаданных, то есть те, которые указаны в перечисленных выше столбцах списка браузеров в консоли администратора. | ||
"FULL" – включает все поля метаданных (перечислены выше). |
Пример
Запрос JSON
Пример запроса Для удобства восприятия пример кода разделен на строки.
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/deviceId?projection=basic
Ответ JSON
При успешном выполнении запроса будет получен код статуса HTTP 200, а вместе с ним – свойства устройства с браузером Chrome.
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
"deviceIdentifiersHistory": {
"records": [
{
"identifiers": {
"machineName": "CLIENT2012",
"serialNumber": "ABCD1234567890" },
"firstRecordTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z"}
],
“has_device_id_collision”: “false”
}
}
Язык запросов для фильтрации данных
Если в запросе используется параметр "query", результаты будут включать только те устройства с браузером Chrome, которые соответствуют всем заданным в параметре значениям. Если в параметре "query" отсутствуют операторы (поля), будет найден браузер, проиндексированные текстовые поля которого содержат все переданные значения. Например, если параметр имеет вид "query=machine 73", будет найден браузер со значениями "machine" и "73" в любом из полей, которые могут быть возвращены, как в следующем примере:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "machine",
"browser_versions": [
"73.0.0.0",
],
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
}
Примечание 1. Сопоставление выполняется по границам слов (любым знакам препинания и пробелам), поэтому частичное совпадение слов невозможно. Результат в примере выше не мог быть получен для запроса "query=komp 73'".
Примечание 2. При сопоставлении слов регистр не учитывается, поэтому по запросу со словом "machine" будут показаны результаты как со словом "machine", так и "Machine".
Чтобы сузить результаты поиска, используйте в запросе приведенные ниже поля. Примечание. В отличие от значений, названия полей указываются с учетом регистра.
Поле | Описание |
---|---|
machine_name | Имя компьютера, связанного с устройством, на котором установлен браузер Chrome. |
os_platform | ОС устройства с браузером Chrome, например Windows. |
arch | Архитектура ЦП устройства с браузером Chrome, например x86_64. |
os_version | Версия ОС устройства с браузером Chrome, например 10.0.16299.904. |
location | Указанное администратором местоположение устройства с браузером Chrome. |
user | Указанный администратором пользователь устройства с браузером Chrome. |
asset_id | Указанный администратором идентификатор объекта устройства с браузером Chrome. |
note | Указанные администратором заметки об устройстве с браузером Chrome. |
register | Дата и время регистрации устройства с браузером Chrome. |
os | Тип и номер основной версии ОС устройства с браузером Chrome, например Windows 10. |
browser_version | Версия браузера Chrome, установленного на устройстве, например 73. |
enrollment_token | Токен регистрации, использованный для регистрации устройства с браузером Chrome. |
report | Дата и время последнего отчета об устройстве с браузером Chrome. |
sync | Дата и время последней синхронизации правил на устройстве с браузером Chrome. |
num_extensions | Количество расширений, установленных на устройстве с браузером Chrome. |
num_policies | Количество правил, заданных на устройстве с браузером Chrome. |
machine_user | Последний пользователь, который вошел в аккаунт на устройстве с браузером Chrome. |
last_activity | Дата и время последнего действия на устройстве с браузером Chrome, например извлечение правил или создание отчета. |
has_device_id_collision | Идентификатор устройства используется несколькими компьютерами, которые браузер Chrome идентифицирует как один и тот же компьютер. Поддерживаемые значения true и false . |
Для полей, которые принимают значение времени (register, report, sync и last_activity), необходимо использовать формат ГГГГ-ММ-ДДТчч:мм:сс, например 2020-01-01T12:00:00. Также можно указать открытый и закрытый временные диапазоны.
Форма |
Значение |
Примеры |
datetime |
Точно в указанную дату или время |
2011-03-23 2011-04-26T14:23:05 |
datetime..datetime |
В пределах указанного диапазона дат и времени (включительно) |
2011-03-23..2011-04-26 |
datetime.. |
В указанные дату и время или позже |
2011-04-26T14:23:05.. |
..datetime |
В указанные дату и время или раньше |
..2011-04-26T14:23:05 |
Примеры фильтрации запросов
Примечание 1. Во всех представленных примерах в запросе используется параметр query
. Значение параметра должно быть правильно экранировано в URL, например если в запросе с несколькими условиями есть пробелы.
Примечание 2. Все запросы можно дополнительно отфильтровать по организационному подразделению, добавив параметр orgUnitPath
.
- Поиск всех устройств, имена компьютеров которых содержат фрагмент "LIX":
machine_name:LIX
- Поиск всех устройств, имена компьютеров которых содержат фрагмент "LIX", а сами компьютеры были зарегистрированы в указанную дату или позже:
machine_name:LIX register: 2011-04-26..
Поиск всех устройств, имена компьютеров которых содержат фрагмент "LIX", а сами компьютеры были зарегистрированы в указанную дату или раньше:
machine_name:LIX register: ..2011-04-26
Запросы, которые не поддерживаются в настоящее время
- Поиск всех устройств, на которых установлено меньше определенного количества расширений (запросы c диапазоном числовых значений не поддерживаются).
- Поиск всех устройств, имена компьютеров которых содержат один из двух возможных фрагментов (параметр OR в запросах не поддерживается).
Как обновить поля устройства с браузером Chrome
Чтобы обновить заполненные администратором поля устройств с браузером Chrome, которые назначены аккаунту, используйте приведенный ниже запрос PUT и включите в него токен доступа, полученный в разделе "Авторизация" выше.
PUT
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/{deviceId}
- customerId – это уникальный идентификатор клиентского аккаунта Google.
- При олицетворении администратора аккаунта вы также можете использовать строку my_customer, которая содержит customerId вашего аккаунта. Также значение customerId можно получить, запросив данные о пользователе. При этом в параметре пути userKey соответствующего оператора необходимо указать свой адрес электронной почты администратора или уникальный идентификатор администратора.
- deviceId – это уникальный идентификатор устройства, который можно найти в ответе на запрос списка устройств с браузером Chrome. Описание синтаксиса запроса, а также свойств запросов и ответов можно найти в документации по API.
В приведенной ниже таблице представлены все параметры, с помощью которых можно передавать информацию в таком запросе.
Параметр | Обязательный | Тип | Описание |
---|---|---|---|
deviceId | Обязательный | Строка | Уникальный идентификатор устройства. Идентификаторы устройств можно получить путем вызова метода browsersdevices.list. Примечание. Этот параметр является обязательным. |
annotatedUser | Необязательный | Строка | Указанный администратором пользователь устройства с браузером Chrome. |
annotatedLocation | Необязательный | Строка |
Указанное администратором местоположение устройства. Это может быть как адрес, так и название места. |
annotatedNotes | Необязательный | Строка | Указанные администратором заметки об устройстве с браузером Chrome. |
annotatedAssetId | Необязательный | Строка |
Идентификатор объекта, указанный администратором или при регистрации. |
Пример
Запрос JSON
Пример запроса Для удобства восприятия пример кода разделен на строки.
PUT https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value
{
"deviceId": "device_id_value",
"annotatedUser": "user 1"
}
Ответ JSON
При успешном выполнении запроса будет получен код статуса HTTP 200, а вместе с ним – свойства устройства с браузером Chrome.
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
"annotatedUser": "user 1"
}
Как удалить устройство с браузером Chrome
Чтобы удалить устройства с браузером Chrome, назначенные аккаунту, используйте запрос DELETE и включите в него токен доступа, полученный в разделе "Авторизация" выше.
DELETE
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices
chromebrowsers/{deviceId}
- customerId – это уникальный идентификатор клиентского аккаунта Google.
- При олицетворении администратора аккаунта вы также можете использовать строку my_customer, которая содержит customerId вашего аккаунта. Также значение customerId можно получить, запросив данные о пользователе. При этом в параметре пути userKey соответствующего оператора необходимо указать свой адрес электронной почты администратора или уникальный идентификатор администратора.
- deviceId – это уникальный идентификатор устройства, который можно найти в ответе на запрос списка устройств с браузером Chrome. Описание синтаксиса запроса, а также свойств запросов и ответов можно найти в документации по API.
Пример
Пример запроса
DELETE https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value
Ответ JSON
При успешном выполнении запроса будет получен код статуса HTTP 200.
Как переместить устройство с браузером Chrome в другое организационное подразделение
Чтобы переместить устройства с браузером Chrome, назначенные аккаунту, из одного организационного подразделения в другое, используйте приведенный ниже запрос POST и включите в него токен доступа, полученный в разделе "Авторизация" выше.
POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices/chromebrowsers/moveChromeBrowsersToOu
- customerId – это уникальный идентификатор клиентского аккаунта Google.
- При олицетворении администратора аккаунта вы также можете использовать строку my_customer, которая содержит customerId вашего аккаунта. Также значение customerId можно получить, запросив данные о пользователе. При этом в параметре пути userKey соответствующего оператора необходимо указать свой адрес электронной почты администратора или уникальный идентификатор администратора.
В приведенной ниже таблице представлены все параметры, с помощью которых можно передавать информацию в таком запросе.
Параметр | Тип | Описание |
---|---|---|
resource_ids | Список строк |
Список уникальных идентификаторов устройств с браузером Chrome, которые нужно переместить в другое подразделение. В рамках запроса можно переместить не более 600 устройств. |
org_unit_path | Строка |
Целевое организационное подразделение, в которое необходимо переместить устройства. Полный путь к организационному подразделению или его уникальный идентификатор с префиксом "id:". |
Пример
Пример запроса
POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/moveChromeBrowsersToOu
{
"org_unit_path": "/new-path",
"resource_ids": ["device_id_value_1","device_id_value_2"],
}
Ответ JSON
При успешном выполнении запроса будет получен код статуса HTTP 200.