通知

在規劃回公司上班的策略嗎？瞭解 Chrome 作業系統如何助您一臂之力。

設定 Chrome 瀏覽器雲端管理服務

使用 Chrome 瀏覽器雲端管理 API

主題

授權

使用所有 Chrome 瀏覽器雲端管理 API 前，您必須先前往 Google 開發人員控制台啟用 Admin SDK API (如果尚未啟用)，方法是點選這個連結，然後選取要啟用 API 的專案。

您可以透過以下 2 種方式取得 API 存取權杖：

  1. 透過服務帳戶以模擬身分使用 OAuth 2.0 (詳情請參閱「以模擬身分進行授權」一節)
  2. 在不模擬身分的情況下使用三足式 OAuth 2.0 (請按照OAuth 2 指南來授權要求)

如要授權存取 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 瀏覽器。

資源表示法

下列 JSON 範本適用於 Directory API 中的 Chromebrowser 資源：

{

"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": strin,

  "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 帳戶的專屬 ID。
  • 如要以帳戶系統管理員的身分操作，您也可以使用 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。
projection 字串 限制系統只能將資訊傳回一組選定的欄位。
    系統接受的值如下：
    "BASIC"：只包含基本中繼資料欄位，例如管理控制台瀏覽器清單資料欄中的欄位 (請參考上方列舉的值)。
    "FULL"：包含所有中繼資料欄位 (請參考上方列舉的值)。
query 字串 使用下方「篩選查詢語言」一節所述的清單頁面查詢語言搜尋字串。
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 帳戶的專屬 ID。
  • 如要以帳戶系統管理員的身分操作，您也可以使用 my_customer 字串來表示帳戶的 customerId，或透過「擷取使用者」作業取得 customerId 值。您可以在該作業的 userKey 路徑參數中，使用系統管理員電子郵件地址或系統管理員專屬使用者 ID 值。
  • deviceId 是裝置的專屬 ID，可以在「擷取所有 Chrome 瀏覽器裝置」作業的回應中找到。如需查詢字串、要求和回應屬性的相關資訊，請參閱 API 參考資料。

以下參考資料說明可在要求中使用的所有查詢字串參數：

參數 類型 說明
deviceId 字串 裝置的專屬 ID。系統會透過 browsersdevices.list 方法，在回應中傳回 deviceId。注意：這是必要參數。
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」參數時，查詢中的每個字詞都必須與特定瀏覽器裝置相符才會生效。如果您未在查詢中指定運算子 (欄位)，搜尋作業會在所有已建立內部索引的文字欄位中，找出含有每個指定字詞的瀏覽器。舉例來說，如果查詢內容是「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。
location 註記的 Chrome 瀏覽器裝置位置。
user 註記的 Chrome 瀏覽器裝置使用者。
asset_id 註記的 Chrome 瀏覽器裝置資產 ID。
note 註記的 Chrome 瀏覽器裝置附註。
register Chrome 瀏覽器裝置的註冊時間。
os Chrome 瀏覽器裝置的作業系統平台和主要作業系統版本組合，例如「Windows 10」。
browser_version Chrome 瀏覽器裝置上安裝的 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 裝置 ID 由多部裝置共用，而 Chrome 瀏覽器會將這些裝置視為同一部裝置。支援的值為 true 和 false。

 

在能接受時間值的欄位 (register、report、sync、last_activity) 中，使用的時間格式應為 YYYY-MM-DDThh:mm:ss，例如 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」參數。請務必在網址中正確逸出參數值，也就是使用多條件要求逸出空格。

注意事項 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 帳戶的專屬 ID。
  • 如要以帳戶系統管理員的身分操作，您也可以使用 my_customer 字串來表示帳戶的 customerId，或透過「擷取使用者」作業取得 customerId 值。您可以在該作業的 userKey 路徑參數中，使用系統管理員電子郵件地址或系統管理員專屬使用者 ID 值。
  • deviceId 是裝置的專屬 ID，可以在「擷取所有 Chrome 瀏覽器裝置」作業的回應中找到。如需查詢字串、要求和回應屬性的相關資訊，請參閱 API 參考資料。

以下參考資料說明可在要求中使用的所有酬載參數：

參數 是否必要 類型 說明
deviceId 必要 字串 裝置的專屬 ID。系統會透過 browsersdevices.list 方法，在回應中傳回 deviceId。注意：這是必要參數。
annotatedUser 選用 字串 系統管理員註記的裝置使用者。
annotatedLocation 選用 字串

系統管理員註記的裝置位址或位置。
annotatedNotes 選用 字串 系統管理員為這部裝置加註的附註。
annotatedAssetId 選用 字串

系統管理員註記或您在註冊時指定的資產 ID。

示例

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 帳戶的專屬 ID。
  • 如要以帳戶系統管理員的身分操作，您也可以使用 my_customer 字串來表示帳戶的 customerId，或透過「擷取使用者」作業取得 customerId 值。您可以在該作業的 userKey 路徑參數中，使用系統管理員電子郵件地址或系統管理員專屬使用者 ID 值。
  • deviceId 是裝置的專屬 ID，可以在「擷取所有 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 帳戶的專屬 ID。
  • 如要以帳戶系統管理員的身分操作，您也可以使用 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
搜尋
清除搜尋內容
關閉搜尋
主選單
17521953535119142753
true
搜尋說明中心
true
true
true
true
true
410864
false
false