設定 Devices API

本頁說明如何設定 Cloud Identity Devices API。您可以透過 Devices API，以程式輔助方式代表管理員佈建資源，例如管理 Google 群組。

啟用 API 並設定憑證

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Identity API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Identity API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

使用具備全網域委派功能的服務帳戶設定 API 存取權

本節說明如何建立及使用服務帳戶存取 Google Workspace 資源。系統不支援使用服務帳戶直接向 Devices API 進行驗證，因此您必須使用這個方法。

建立服務帳戶並設定全網域委派

如要建立服務帳戶並下載服務帳戶金鑰，請完成下列步驟：

1. 如要建立服務帳戶，請按照下列步驟操作：

   1. 前往 Google Cloud 控制台的 IAM 服務帳戶頁面：

      前往服務帳戶

   2. 按一下 「建立服務帳戶」。

   3. 在「服務帳戶詳細資料」下方，輸入服務帳戶的名稱、ID 和說明，然後按一下「建立並繼續」。

   4. 選用：在「Grant this service account access to project」(將專案存取權授予這個服務帳戶) 下方，選取要授予服務帳戶的 IAM 角色。

   5. 按一下「繼續」。

   6. 選用：在「Grant users access to this service account」(將這個服務帳戶的存取權授予使用者) 下方，新增允許使用及管理服務帳戶的使用者或群組。

   7. 按一下 [完成]。

2. 如要讓服務帳戶使用全網域委派功能存取 Devices API，請按照「為服務帳戶設定全網域委派」一文的說明操作。

3. 如要建立及下載服務帳戶金鑰，請按照下列步驟操作。

   重要事項： 如未妥善管理服務帳戶金鑰，可能會產生安全性風險，請盡可能 選用比服務帳戶金鑰更安全的替代方案。如必須使用服務帳戶金鑰進行驗證，您有責任保護私密金鑰的安全，並執行 管理服務帳戶金鑰的最佳做法一文所述的其他作業。如果無法建立服務帳戶金鑰，可能是因為貴機構已停用這項功能。詳情請參閱「 管理預設安全機構資源」。

   如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「 外部來源憑證的安全規定」。

   1. 按一下您建立的服務帳戶電子郵件地址。
   2. 按一下「Keys」(金鑰) 分頁標籤。
   3. 在「新增金鑰」下拉式清單中，選取「建立新的金鑰」。

   4. 點選「建立」。

      系統會產生新的公開和私密金鑰組，並以 JSON 格式儲存為憑證檔案，然後下載到您的電腦。這個檔案是金鑰的唯一副本。您必須負責妥善保管。如果遺失金鑰組，就必須產生新的金鑰組。

查看記錄項目

查看記錄項目時，請注意稽核記錄會將所有服務帳戶動作顯示為由使用者發起。這是因為全網域委派功能會允許服務帳戶模擬管理員使用者。

初始化憑證

在程式碼中初始化憑證時，請呼叫憑證上的 with_subject()，指定服務帳戶採取的電子郵件地址。例如：

Python

credentials = service_account.Credentials.from_service_account_file(
  'SERVICE_ACCOUNT_CREDENTIAL_FILE',
  scopes=SCOPES).with_subject(USER
)

更改下列內容：

• SERVICE_ACCOUNT_CREDENTIAL_FILE：您在本文件稍早建立的服務帳戶金鑰檔案
• USER：服務帳戶模擬的使用者

例項化用戶端

以下範例說明如何使用服務帳戶憑證建立用戶端例項。

Python

from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.devices']

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    'SERVICE_ACCOUNT_CREDENTIAL_FILE',
    scopes=SCOPES
  )

  delegated_credentials = credentials.with_subject('USER')

  service_name = 'cloudidentity'
  api_version = 'v1'
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    credentials=delegated_credentials)

  return service

更改下列內容：

• SERVICE_ACCOUNT_CREDENTIAL_FILE：您在本文件稍早建立的服務帳戶金鑰檔案
• USER：服務帳戶模擬的使用者

現在可以開始呼叫 Devices API。

如要改為以使用者身分進行驗證，請將服務帳戶中的 credential 物件，替換為您在「取得 OAuth 2.0 權杖」中取得的 credential。

安裝 Python 用戶端程式庫

如要安裝 Python 用戶端程式庫，請執行下列指令：

  pip install --upgrade google-api-python-client google-auth \
    google-auth-oauthlib google-auth-httplib2

如要進一步瞭解如何設定 Python 開發環境，請參閱 Python 開發環境設定指南。