針對 Classroom 功能指定自訂管理員角色

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

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

• 臨時存取 Classroom 中的課程 為教師提供支援、張貼公告等，不必成為課程的 固定共同授課老師。

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

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

自動指派自訂角色

如要自動指派自訂角色，請按照下列步驟操作：

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

必要條件

1. 請參閱快速入門導覽課程指南，瞭解如何使用 JavaScript、Python 和 Java 等語言，設定及執行 Google API 應用程式。
2. 閱讀 Groups API 總覽。
3. 如要使用本指南所述的任何 Cloud Identity API，您必須先設定 Cloud Identity。這些 API 可用來建立群組，並指派管理員權限。
4. 設定 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 的成員。

如要將成員新增至群組，請使用下列 POST 要求。

Directory API members.insert：

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 提供的預建角色更具體地限制管理員存取權。您可以將角色指派給使用者或安全性群組。如要進一步瞭解角色建立限制，請參閱自訂角色和角色指派限制。

如要建立新角色，請使用下列 POST 要求。

Directory API roles.insert：

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 分析

如要建立可存取 Analytics 資料的自訂角色，必須具備 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 開發人員支援