管理員動作

網域管理員可以透過多項控管功能，管理網域使用者可存取的功能和應用程式。本頁面說明這些功能、這些功能對外部整合的影響或實用性，以及相關的 API 要求。

管理未滿 18 歲使用者存取第三方應用程式

管理員必須在 Google 管理控制台中設定第三方應用程式，供未滿 18 歲的使用者存取。如果管理員未設定應用程式，未滿 18 歲的使用者就無法透過 Google Workspace for Education 帳戶存取該應用程式。

如果開發人員為未滿 18 歲的 Google Workspace for Education 使用者建構應用程式，則無須採取任何行動。只有管理員才能透過管理控制台使用者介面設定第三方應用程式，無法以程式輔助完成這項操作。

為 Classroom 功能指派自訂管理員角色

管理員可以在管理控制台中建立自訂管理員角色，允許特定個人或群組 (須具備 Education Plus 授權) 執行下列操作：

• 查看 Classroom 分析，瞭解作業完成情況、成績趨勢和 Classroom 採用度等資料。

• 暫時存取 Classroom 中的課程，不必指派共同授課老師。

本指南說明如何使用 Google API 在網域中設定這些功能。

警告： 只有超級管理員才能完成本指南所述的操作。

自動指派自訂角色

本指南將說明如何完成下列步驟，自動執行自訂角色指派程序：

1. 建立安全群組，將可存取這些功能的使用者納入其中。
2. 將成員新增至群組。
3. 選取正確的權限，建立自訂管理員角色。
4. 擷取機構單位 ID。
5. 將自訂管理員角色套用至新建立的群組。

必要條件

1. 請參閱快速入門導覽課程指南，瞭解如何使用 JavaScript、Python 和 Java 等語言，設定及執行 Google API 應用程式。
2. 如要使用本指南所述的任何 Cloud Identity API，請先設定 Cloud Identity。這些 API 可用來建立群組，並指派管理員權限。
3. 如要為一群使用者提供自訂角色存取權，而非個別使用者，請參閱 Groups API 總覽並設定 Groups API。

建立安全性群組

重要事項： 如果您不需要建立安全群組，而是想為個別使用者提供這些功能的存取權，請跳至「建立自訂管理員角色」步驟。

使用 groups.create 方法建立安全性群組。如果要求的 labels 欄位中包含安全性標籤，群組就會設為安全性群組。如要進一步瞭解如何建立安全群組，以及相關限制，請參閱建立安全群組指南。

POST https://cloudidentity.googleapis.com/v1/groups

您可以選擇性加入 InitialGroupConfig 查詢參數，初始化群組擁有者：

POST https://cloudidentity.googleapis.com/v1/groups&initialGroupConfig={initialGroupConfig}

提出這項要求的帳戶必須具備下列其中一個範圍：

• https://www.googleapis.com/auth/cloud-identity.groups
• https://www.googleapis.com/auth/cloud-identity
• https://www.googleapis.com/auth/cloud-platform

要求主體

要求主體包含要建立的群組詳細資料。customerId 開頭必須是「C」(例如 C046psxkn)。找出您的客戶 ID。

{
   parent: "customers/<customer-id>",
   description: "This is the leadership group of school A.",
   displayName: "Leadership School A",
   groupKey: {
      id: "[e-mail]"
   },
   labels: {
      "cloudidentity.googleapis.com/groups.security": "",
      "cloudidentity.googleapis.com/groups.discussion_forum": ""
   }
}

回應

回應包含 Operation 資源的新例項。

{
   done: true,
   response: {
      @type: "type.googleapis.com/google.apps.cloudidentity.groups.v1.Group",
      name: "groups/<group-id>", // unique group ID
      groupKey: {
         id: "[e-mail]" // group email address
      },
      parent: "customers/<customer-id>",
      displayName: "Leadership School A",
      description: "This is the leadership group of school A.",
      createTime: "<created time>",
      updateTime: "<updated time>",
      labels: {
         "cloudidentity.googleapis.com/groups.security": "",
         "cloudidentity.googleapis.com/groups.discussion_forum": ""
      }
   }
}

新增群組成員

建立群組後，下一步就是新增成員。群組成員可以是使用者或其他安全性群組。如果您將群組新增為另一個群組的成員，成員資格最多可能需要 10 分鐘才會傳播。此外，如果群組成員資格出現週期，API 會傳回錯誤。舉例來說，如果 group1 是 group2 的成員，則 group2 不能是 group1 的成員。

如要將成員新增至群組，請對 Directory API members.insert 方法發出下列 POST 要求：

POST https://admin.googleapis.com/admin/directory/v1/groups/{groupKey}/members

groupKey 路徑參數是新成員的群組電子郵件地址或群組的專屬 ID。

提出 POST 要求的帳戶必須具備下列其中一個範圍：

• https://apps-apis.google.com/a/feeds/groups/
• https://www.googleapis.com/auth/admin.directory.group
• https://www.googleapis.com/auth/admin.directory.group.member

要求主體

要求主體包含要建立的 member 詳細資料。

{
   email: "[e-mail]",
   role: "MEMBER", // can be `MEMBER`, `OWNER`, `MANAGER`
}

回應

回應包含新的成員例項。

{
   kind: "admin#directory#member",
   etag: "<etag-value>", // role's unique ETag
   id: "4567", // group member's unique ID
   email: "[e-mail]",
   role: "MEMBER",
   type: "GROUP",
   status: "ACTIVE"
}

如要新增多位成員，請為每位使用者提出這項要求。您可以批次處理這些要求，減少用戶端必須建立的 HTTP 連線數量。

建立具備權限的自訂管理員角色

您可以使用 Directory API 透過角色型存取權控管 (RBAC)，管理 Google Workspace 網域中各項功能的存取權。您可以建立具備權限的自訂角色，比 Google Workspace 提供的預建角色更具體地限制管理員存取權。您可以將角色指派給使用者或安全性群組。如要進一步瞭解角色建立限制，請參閱自訂角色和角色指派限制。

如要建立新角色，請對 Directory API roles.insert 方法發出下列 POST 要求：

POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roles

customerId 與本指南步驟 1 中使用的相同。

提出 POST 要求的帳戶必須具備下列範圍：

• https://www.googleapis.com/auth/admin.directory.rolemanagement

要求主體

要求主體包含要建立的 role 詳細資料。針對應透過這個角色授予的每項權限，新增 privilegeName 和 serviceId。

Classroom 分析

如要建立可存取數據分析資料的自訂角色，必須具備 EDU_ANALYTICS_DATA_ACCESS 權限，且 serviceId 必須設為 019c6y1840fzfkt。

{
  roleName: "Education Admin", // customize as needed
  roleDescription: "Access to view analytics data", // customize as needed
  rolePrivileges: [
     {
        privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
        serviceId: "019c6y1840fzfkt"
     }
  ]
}

課程暫時存取權

如要建立可暫時存取課程的自訂角色，必須具備 ADMIN_OVERSIGHT_MANAGE_CLASSES 權限，並將 serviceId 設為 019c6y1840fzfkt。

{
  roleName: "Education Admin", // customize as needed
  roleDescription: "Access to manage classes privilege", // customize as needed
  rolePrivileges: [
     {
        privilegeName: "ADMIN_OVERSIGHT_MANAGE_CLASSES",
        serviceId: "019c6y1840fzfkt"
     }
  ]
}

呼叫 privileges.list 方法，擷取 privilegeIds 和 serviceIds 清單。

回應

回應會包含新的角色例項。

Classroom 分析

{
  kind: "admin#directory#role",
  etag: "<etag-value>",  // role's unique ETag
  roleId: "<role-id>",   // role's unique ID
  roleName: "Education Admin",
  roleDescription: "Access to view analytics data",
  rolePrivileges: [
     {
        privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
        serviceId: "019c6y1840fzfkt"
     }
  ],
  isSystemRole: false,
  isSuperAdminRole: false
}

課程暫時存取權

{
  kind: "admin#directory#role",
  etag: "<etag-value>",  // role's unique ETag
  roleId: "<role-id>",   // role's unique ID
  roleName: "Education Admin",
  roleDescription: "Access to manage classes privilege",
  rolePrivileges: [
     {
        privilegeName: "ADMIN_OVERSIGHT_MANAGE_CLASSES",
        serviceId: "019c6y1840fzfkt"
     }
  ],
  isSystemRole: false,
  isSuperAdminRole: false
}

擷取機構單位 ID

您可以使用機構單位 ID，將自訂管理員角色的存取權限制為一或多個機構單位。使用 OrgUnit API 擷取 orgUnitId。

Classroom 分析

建議您為特定使用者或群組指派自訂管理員角色時，選取學生機構單位和老師機構單位。這樣一來，獲派自訂管理員權限的使用者，就能存取機構單位中學生和課程層級的資料。如果省略學生機構單位，指定使用者就無法存取學生資料。如果省略教師機構單位，指定使用者就無法存取課程層級資料。

課程暫時存取權

您可以允許具有自訂管理員角色的使用者存取特定機構單位的課程，藉此限制臨時課程存取權。如果限制機構單位的存取權，指派自訂管理員角色的群組只能存取主要任課老師屬於該機構單位的課程。

指派自訂管理員角色

如要將自訂管理員角色指派給群組，請使用下列 POST 要求。如要瞭解角色指派限制，請參閱自訂角色和角色指派限制指南。

Directory API roleAssignments.insert：

POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roleassignments

注意： 您可以在這個端點使用 my_customer 別名，代表您帳戶的 customerId。customerId 也會做為users 資源的一部分傳回。您必須提供客戶或網域參數。

指派給群組或個別使用者

如要將權限指派給群組，請在要求主體的 assignedTo 欄位中加入 groupId。groupId 是在「建立安全性群組」步驟中取得。如要將權限指派給個別使用者，請在要求主體的 assignedTo 欄位中加入使用者 ID。如要擷取使用者 ID，請呼叫 users.get，並將使用者的電子郵件地址指定為 userKey 參數，或呼叫 users.list。

提出 POST 要求的帳戶必須具備下列範圍：

• https://www.googleapis.com/auth/admin.directory.rolemanagement

要求主體

要求主體包含要建立的 RoleAssignment 詳細資料。您必須為要與這個群組建立關聯的每個機構單位提出一項要求。

{
   roleId: "<role-id>",        // role's unique ID obtained from Step 3
   assignedTo: "<id>",         // group ID or user ID
   scopeType: "ORG_UNIT",      // can be `ORG_UNIT` or `CUSTOMER`
   orgUnitId: "<org-unit-id>"  // organizational unit ID referenced in Step 4
}

回應

回應包含 RoleAssignment 的新例項。

{
   kind: "admin#directory#roleAssignment",
   etag: "<etag-value>",
   roleAssignmentId: "<role-assignment-id>",
   roleId: "<role-id>",
   assignedTo: "<group-id or user-id>",
   assigneeType: "GROUP",
   scopeType: "ORG_UNIT",
   orgUnitId: "<org-unit-id>"
}

資源

詳情請參閱：

• Directory API 總覽
• Directory API 專屬的驗證與授權
• Directory API REST 說明文件
• Admin SDK API 開發人員支援