通知

要制定办公室复工策略？了解 Chrome 操作系统可以为您提供哪些帮助。

设置 Chrome 浏览器云管理

使用 Chrome 浏览器云管理 API

主题

授权

在使用所有 Chrome 浏览器云管理 API 之前，您需要先在 Google 开发者控制台中启用 Admin SDK API（如果尚未启用），方法是，点击此链接并选择您要启用 API 的项目。

然后，您可以通过以下两种方式获取令牌来访问该 API：

  1. 使用服务账号进行模拟的 Oauth2.0（请参阅“通过模拟进行授权”部分）
  2. 不进行模拟的三方 Oauth2.0（您可以按照 Oauth2 指南向请求授权）

您需要以下范围才能授权您访问 Chrome 浏览器云管理 API：

https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly

或

https://www.googleapis.com/auth/admin.directory.device.chromebrowsers

通过模拟授权

如需使用模拟服务账号，您需要：

  1. 创建服务账号，并为此服务账号获取必要的服务账号密钥。您可以按照此处的说明创建服务账号并获取服务账号密钥。
  2. 此服务账号的客户端 ID 需要获得上面列出的 OAuth 范围的授权。为此，您必须打开管理控制台，依次点击安全性 -> API 控件 -> 管理全网域授权。然后，您会添加一个新客户。在此对话框中，客户端 ID 对应于您的服务账号的唯一 ID。

使用服务账号密钥时，您需要使用偏好语言的 Google API 客户端库为服务账号请求 OAuth 访问令牌。

 

此外，在请求 OAuth 令牌时，OAuth 令牌请求还需要模拟您网域中的管理员用户。

例如，下面是一些使用 Java API 客户端库检索 oauth 令牌的示例代码。

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 浏览器。

资源表示法

Directory API 中的 Chromebrowser 资源使用以下 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,

    "filename": 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 路径参数中，使用您的管理员电子邮件地址或管理员唯一用户 ID 值。

以下是可在请求中使用的所有查询字符串参数的参考信息：

参数值 类型 说明
maxResults 整数 页面中结果的数量上限。默认值和最大值均为 100。
orderBy 字符串 用于对结果进行排序的 Chrome 浏览器设备属性。
    可接受以下值：
    "id" - 已安装 Chrome 浏览器的设备 ID。
    "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 浏览器设备资产 ID。
    "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 字符串 组织部门的完整路径或其唯一 ID。
groupId 字符串 群组的完整资源名称（格式为 groups/{group}）或其唯一 ID。
pageToken 字符串 pageToken 查询参数用于请求下一页查询结果。下一个请求的 pageToken 查询参数是上一个响应中的 nextPageToken。
投影 字符串 限制返回给一组选定字段的信息。
    可接受的值包括：
    "BASIC" - 仅包含基本元数据字段（即上方枚举的管理控制台浏览器列表列中的字段）
    "FULL" - 包括所有元数据字段（如上文枚举）
查询 字符串 使用下文“过滤查询语言”中所述的列表页面查询语言搜索字符串。
sortOrder 字符串 返回升序还是降序结果。必须与 orderBy 参数搭配使用。
    可接受的值包括：
    "ASCENDING" - 升序。
    "DESCENDING" - 降序。

示例：按机器名称过滤设备

第一个示例使用 query=machine_name:CLIENT2012 搜索特定的机器名称。响应中包含单个 Chrome 浏览器资源，其中 machineName 是帮助台：

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 状态代码。系统还会返回一系列与查询参数匹配的浏览器设备：

{
  "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 路径参数中，使用您的管理员电子邮件地址或管理员唯一用户 ID 值。
  • deviceId 是设备的唯一标识符，可在“检索所有 Chrome 浏览器设备”操作的响应中找到。对于查询字符串、请求和响应属性，请参阅 API 参考文档。

以下是可在请求中使用的所有查询字符串参数的参考信息：

参数值 类型 说明
deviceId 字符串 设备的唯一 ID。系统会在 browsersdevices.list 方法的响应中返回 deviceId。注意：此参数是必需的。
投影 字符串 确定响应是包含完整的属性列表，还是仅包含一部分属性。
    可接受的值包括：
    "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”参数时，查询中的每个字词都必须在特定浏览器设备中匹配才能有效。如果您未在查询中指定运算符（字段），搜索将找到一个在所有内部索引文本字段中具有所有指定字词的浏览器。例如，如果您的查询是“query=machine 73”，这将返回一个浏览器，它在所有可能在浏览器设备中返回的字段中包含“machine”和“73”，如下所示：

{
  "deviceId": "device_id_value",
  "kind": "admin#directory#browserdevice",
  "osPlatform": "Windows",
  "osVersion": "6.3.9600.19542",
  "machineName": "machine_name",
  "browser_versions": [
    "73.0.0.0",
  ],
  "lastActivityTime": "2019-11-27T12:55:27.230Z",
  "virtualDeviceId": "virtual_device_id",
  "orgUnitPath": "/Org-unit path",
}

 

注意 1：匹配会在字词边界（任何标点符号或空格）上进行，因此您将无法对字词进行部分匹配。在上面的示例中，您无法执行 query='mach 73'。

注意 2：字词匹配不区分大小写，因此带有“machine”的查询会同时匹配“Machine”和“machine”。

 

您可以指定以下字段，将搜索定位到特定字段（注意：虽然查询字词不区分大小写，但字段名称区分大小写）。

字段 说明
machine_name Chrome 浏览器设备的机器名称。
os_platform Chrome 浏览器设备的操作系统平台，例如 Windows。
arch Chrome 浏览器设备的 CPU 架构，例如 x86_64。
os_version Chrome 浏览器设备的操作系统版本，例如 10.0.16299.904。
位置权限 Chrome 浏览器设备的注释位置。
位用户 Chrome 浏览器设备的注释用户。
asset_id Chrome 浏览器设备的注释资产 ID。
note Chrome 浏览器设备的注释说明。
register Chrome 浏览器设备的注册时间。
os Chrome 浏览器设备的操作系统平台和主要操作系统版本组合（例如“Windows 10”）
browser_version Chrome 浏览器设备上安装的 Chrome 浏览器（例如 73）
enrollment_token 用于注册 Chrome 浏览器设备的注册令牌。
report Chrome 浏览器设备的上次报告时间
同步 Chrome 浏览器设备的上次政策同步时间。
num_extensions Chrome 浏览器设备报告的扩展程序数量。
num_policies Chrome 浏览器设备报告的政策数量。
machine_user 上次报告的 Chrome 浏览器设备用户。
last_activity Chrome 浏览器设备上次显示活动（政策提取或报告）的时间。
has_device_id_collision 设备 ID 由多台机器共用，Chrome 浏览器会将这些机器标识为同一台机器。支持的值为 true 和 false。

 

对于接受时间（注册、报告、同步、last_activity）的字段，时间格式为 YYYY-MM-DDThh:mm:ss（例如 2020-01-01T12:00:00）。您还可以为时间指定开放或关闭范围：

 

表单

含义

示例

日期时间

正好为指定的日期或时间

2011-03-23

2011-04-26T14:23:05

日期时间..日期时间

在指定的日期或时间间隔内（包含最早和最晚的日期或时间）

2011-03-23..2011-04-26

日期时间..

不早于指定日期或时间

2011-04-26T14:23:05..

..日期时间

不晚于指定日期或时间

..2011-04-26T14:23:05
 

过滤器查询示例

 

注意 1：所提供的全部示例都在请求中使用“query”参数。它们的参数值必须在网址中正确转义（即，对多个条件请求转义空格）。

注意 2：通过将“orgUnitPath”查询参数添加到请求中，可以进一步过滤出特定组织部门的查询。

 

  1. 查找机器名称中包含某个字词的所有设备：
    1. machine_name:LIX
  2. 查找机器名称中包含某个字词且在特定日期之后注册的所有设备：
    1. machine_name:LIX register:​2011-04-26..
  3. 查找机器名称中包含某个字词且注册日期早于特定日期的所有设备：
    1. machine_name:LIX register:​..2011-04-26

 

目前不支持的查询：

  1. 查找安装了不到特定数量的扩展程序的所有设备（不支持对数值进行范围查询）。
  2. 查找其机器名称包含两个潜在字词之一（在查询中使用 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 路径参数中，使用您的管理员电子邮件地址或管理员唯一用户 ID 值。
  • deviceId 是设备的唯一标识符，可在“检索所有 Chrome 浏览器设备”操作的响应中找到。对于查询字符串、请求和响应属性，请参阅 API 参考文档。

以下是可在请求中使用的所有载荷参数，仅供参考：

参数 是否必需 类型 说明
deviceId 必需 字符串 设备的唯一 ID。系统会在 browsersdevices.list 方法的响应中返回 deviceId。注意：此参数是必需的。
annotatedUser 可选 字符串 管理员注释的设备用户。
annotatedLocation 可选 字符串

管理员注释的设备的地址或位置。
annotatedNotes 可选 字符串 管理员注释的此设备的说明
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 路径参数中，使用您的管理员电子邮件地址或管理员唯一用户 ID 值。
  • 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 路径参数中，使用您的管理员电子邮件地址或管理员唯一用户 ID 值。

以下是可在请求中使用的所有载荷参数，仅供参考：

参数值 类型 说明
resource_ids 字符串列表

要移动的 Chrome 浏览器设备的唯一设备 ID 的列表。每个请求最多可以移动 600 个浏览器。
org_unit_path 字符串

移动设备的目标组织部门。组织部门的完整路径或带有“id:”前缀的 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 状态代码。

该内容对您有帮助吗？

您有什么改进建议？
true
搜索
清除搜索内容
关闭搜索框
主菜单
2694098931193811860
true
搜索支持中心
true
true
true
true
true
410864
false
false