管理员可以在管理控制台中创建自定义管理员角色,以允许拥有教育 Plus 版许可的某些个人或群组执行以下操作:
查看 Google 课堂分析,了解作业完成情况、成绩趋势和 Google 课堂采用情况等数据。
临时访问 Google 课堂中的课程,以便为教育工作者提供支持、发布通知等,而无需分配为常任助理教师。
本指南介绍了如何使用 Google API 在您的网域中设置这些功能。
自动执行自定义角色分配流程
如需自动执行自定义角色分配流程,请执行以下操作:
前提条件
- 阅读快速入门指南,了解如何使用 Google API 以 JavaScript、Python 和 Java 等语言设置和运行应用。
- 阅读 Groups API 概览。
- 在使用本指南中所述的任何 Cloud Identity API 之前,您必须设置 Cloud Identity。这些 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: "leadership_school_a@example.com"
},
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: "leadership_school_a@example.com" // 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: "person_one@example.com",
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: "person_one@example.com",
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
。
Google 课堂分析
您必须拥有 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
的列表。
响应
响应包含角色的新实例。
Google 课堂分析
{
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
。
Google 课堂分析
在向特定用户或群组分配自定义管理员角色时,建议您选择学生组织部门和教师组织部门。这样一来,指定具有自定义管理员权限的用户可以访问组织部门的学生和课程级数据。如果省略学生组织部门,指定用户将无法访问学生数据。如果省略教师组织部门,指定用户将无法访问课程级数据。
课程临时访问权限
您可以限制具有自定义管理员角色的用户访问特定组织部门中的课程,从而限制课程临时访问权限。如果限制对某个组织部门的访问权限,则分配有自定义管理员角色的群组只能访问课程的主讲教师在该组织部门中的课程。
分配自定义管理员角色
要为群组分配自定义管理员角色,请使用以下 POST 请求。如需了解角色分配限制,请参阅自定义角色和角色分配限制指南。
Directory API roleAssignments.insert
:
POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roleassignments
分配给群组或单个用户
如果要将权限分配给群组,请在请求正文的 assignedTo
字段中添加 groupId
。groupId
是在创建安全群组步骤中获得的。如果要向单个用户分配权限,请在请求正文的 assignedTo
字段中添加该用户的 ID。您可以通过调用 users.get
并将用户的电子邮件地址指定为 userKey
参数或调用 users.list
来检索用户的 ID。
发出 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>"
}
资源
如需了解更多信息,请访问: