Как настроить облачное управление браузером Chrome

Как использовать Chrome Browser Cloud Management API

Далее: Начало работы с интеграцией Postman API для облачного управления браузером Chrome

Содержание

Авторизация

Прежде чем использовать любой из Chrome Browser Cloud Management API, нужно включить Admin SDK API (если вы этого ещё не сделали) в Google Developer Console и выбрать проект, для которого вы хотите активировать API.

После этого вы сможете получить токен доступа к API двумя способами:

По протоколу OAuth 2.0 с олицетворением при использовании сервисного аккаунта (инструкции приведены в разделе "Авторизация с олицетворением" ниже).
По трехстороннему протоколу OAuth 2.0 без олицетворения (инструкции по авторизации запросов вы найдете в руководстве по настройке OAuth 2.0).

Для авторизации доступа к Chrome Browser Cloud Management 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).

Ресурс ChromeBrowser

Браузеры Chrome, зарегистрированные в системе облачного управления браузером Chrome.

Представление ресурса

Ресурс 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":
1. machine_name:LIX
Поиск всех устройств, имена компьютеров которых содержат фрагмент "LIX", а сами компьютеры были зарегистрированы в указанную дату или позже:
1. machine_name:LIX register: 2011-04-26..
Поиск всех устройств, имена компьютеров которых содержат фрагмент "LIX", а сами компьютеры были зарегистрированы в указанную дату или раньше:
1. 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

{
  "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.

Эта информация оказалась полезной?

Как можно улучшить эту статью?