本页面介绍如何使用 Directory API 管理 Google 网上论坛:
- 创建组
- 更新群组
- 添加群组别名
- 检索群组
- 检索网域或帐号的所有群组
- 检索成员的所有群组
- 检索所有群组别名
- 删除群组别名
- 删除群组
创建组
如需创建群组,请使用以下 POST
请求并添加授权请求中所述的授权。您可以为与该帐号关联的任何网域创建群组。如需了解查询字符串、请求和响应属性,请参阅 groups.insert
方法。
POST https://admin.googleapis.com/admin/directory/v1/groups
以下 JSON 请求显示了一个用于创建群组的示例请求正文。该群组的电子邮件地址为 sales_group@example.com:
{ "email": "sales_group@example.com", "name": "Sales Group", "description": "This is the Sales group." }
成功的响应将返回 HTTP 201
状态代码以及新组的属性。
更新群组
如需更新群组的设置,请使用以下 PUT
请求并添加授权请求中所述的授权。groupKey
是群组的电子邮件地址、任何群组别名的电子邮件地址或群组的唯一 id
。如需了解查询字符串、请求和响应属性,请参阅 groups.update
方法。
PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey
通常,Google 建议不要将群组的电子邮件地址用作持久性数据的密钥,因为电子邮件地址随时可能更改。
在以下示例中,唯一的 groupKey
为 nnn
,该群组的名称为 APAC 销售组:
PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{ "email": "sales_group@example.com", "name": "APAC Sales Group" }
对于更新请求,您只需在请求中提交更新后的信息。您无需在请求中输入该组的所有属性。
成功的响应将返回 HTTP 201
状态代码以及新组的属性:
{ "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "APAC Sales Group", "directMembersCount": "5", "description": "This is the APAC sales group.", "adminCreated": true, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }
添加群组别名
如需添加群组别名,请使用以下 POST
请求,并包含授权请求中所述的授权。groupKey
是群组的电子邮件地址、任何群组别名的电子邮件地址或群组的唯一 id
。如需了解查询字符串、请求和响应属性,请参阅 groups
资源。
POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
通常,Google 建议不要将群组的电子邮件地址用作持久性数据的密钥,因为电子邮件地址随时可能更改。
以下 JSON 请求显示了创建群组别名的请求示例。groupKey
是实例组的唯一 id
,由 NNNN
表示
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{ "alias": "best_sales_group@example.com" }
成功的响应将返回 HTTP 201
状态代码以及新群组别名的属性。
检索群组
如需检索群组,请使用以下GET
请求并添加授权请求中所述的授权。groupKey
是群组的电子邮件地址、任何群组别名的电子邮件地址或群组的唯一 id
。如需了解查询字符串、请求和响应属性,请参阅 groups.get
方法。GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey
通常,Google 建议不要将群组的电子邮件地址用作持久性数据的密钥,因为电子邮件地址随时可能更改。
在以下示例中,唯一 groupKey
ID 为 nnnn
:
GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn
如果响应成功,将返回 HTTP 200
状态代码和该群组的设置:
{ "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "APAC Sales Group", "directMembersCount": "5", "description": "This is the APAC sales group.", "adminCreated": true, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }
检索网域或帐号的所有群组
如需检索特定网域或帐号的所有群组,请使用以下 GET
请求并添加授权请求中所述的授权。如需了解查询字符串、请求和响应属性,请参阅 groups.list
方法。为确保可读性,此示例使用换行符:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name &customer=my_customer or customerId&pageToken=pagination token &maxResults=max results
在检索某个网域或帐号的所有群组时,请考虑以下事项:
- 子网域的所有群组:使用
domain
参数和域名。 - 帐号的所有组:使用
customer
参数以及my_customer
或帐号的customerId
值。作为帐号管理员,请使用字符串my_customer
来表示您帐号的customerId
。如果您是访问转销商客户帐号的转销商,请使用转销商帐号的customerId
。对于customerId
值,请在检索网域中的所有用户操作的请求中,使用帐号的主域名。生成的响应具有customerId
值。 - 同时使用
domain
和customer
参数:Directory API 会返回domain
的所有群组。 - 不使用
domain
和customer
参数:Directory API 会返回与my_customer
关联的帐号的所有群组。这是发出请求的管理员的帐号customerId
。 - 同时使用
customer
和userKey
参数:Directory API 会返回错误。您必须使用这些参数发出两个单独的请求。
在以下示例中,帐号管理员使用 my_customer
请求列出帐号的所有群组:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2
在以下示例中,转销商管理员的请求返回具有 customerId C03az79cb
的转销商帐号的所有群组。每个响应页面返回的结果数上限为 2。
此响应中有一个针对后续用户列表的 nextPageToken
:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2
成功的响应将返回一个 HTTP 200
状态代码以及群组(按群组电子邮件地址的字母顺序):
{ "kind": "directory#groups", "groups": [ { "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "support@sales.com", "name": "Sales support", "directMembersCount": "6", "description": "The sales support group", "adminCreated": true }, { "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "travel@sales.com", "name": "Sales travel", "directMembersCount": "2", "description": "The travel group supporting sales", "adminCreated": false, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }, "nextPageToken": "NNNN" }
检索成员的所有群组
如需检索成员具有订阅的所有群组,请使用以下 GET
请求并添加授权请求中所述的授权。为确保可读性,此示例使用换行符:
GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key ?pageToken=pagination token &maxResults=maximum results per response page
- 成员可以是用户,也可以是群组。
userKey
可以是用户的主电子邮件地址、用户的别名电子邮件地址、群组的主电子邮件地址、群组的电子邮件别名或用户的唯一id
(可通过“检索用户”操作找到)。userKey
中指定的用户或群组必须属于您的网域。- 对于包含大量组的响应,请使用
pageToken
查询字符串。在分页的情况下,响应会返回nextPageToken
属性,该属性会为下一页响应结果提供令牌。您的下一个请求会将此令牌用作pageToken
查询字符串值。 - 同时使用
customer
和userKey
参数:Directory API 会返回错误。您必须使用这些参数发出两个单独的请求。
如需了解请求和响应属性,请参阅 groups.list
方法。
成功的响应会返回 HTTP 200 状态代码和成员信息列表:
- 返回成员拥有订阅的所有群组(包括用户网域外的群组)。
- 系统会按照每个群组电子邮件地址的字母顺序返回群组。
- 在响应正文中,
id
是该组的唯一 ID。 - 在响应中,列出的用户网域以外的群组不包含外部群组的别名。
{ "kind": "directory#groups", "groups": [ { "kind": "directory#group", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "sale group", "directMembersCount": "5", "description": "Sales group" }, { "kind": "directory#group", "id": "group's unique ID", "etag": "group's unique ETag", "email": "support_group.com", "name": "support group", "directMembersCount": "5", "description": "Support group" } ], "nextPakeToken": "NNNNN" }
检索所有群组别名
如需检索群组的所有别名,请使用以下GET
请求,并包含授权请求中所述的授权。groupKey
可以是群组的主电子邮件地址、群组的唯一 id
或任何群组别名的电子邮件地址。如需了解请求和响应属性,请参阅 groups
资源。
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
如果响应成功,则会返回 HTTP 201
状态代码和群组别名列表。
删除群组别名
如需删除群组的别名,请使用以下DELETE
请求并添加授权请求中所述的授权。groupKey
可以是群组的主电子邮件地址、群组的唯一 id
或任何群组别名的电子邮件地址。aliasId
是要删除的别名。如需了解请求和响应属性,请参阅 groups
资源:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId
成功的响应将返回 HTTP 201
状态代码。
删除群组
如需删除群组,请使用以下 DELETE
请求并添加向请求授权中所述的授权。groupKey
是实例组的唯一 id
:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
例如,以下 DELETE
请求会删除具有 nnnn
群组 id
的群组:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn
成功的响应将返回 HTTP 200
状态代码。
删除群组后,会出现以下情况:
- 群组中的所有成员都会被删除。系统不会删除成员的用户帐号。
- 此群组归档已删除。
- 无法递送发送至已删除群组地址的邮件。相反,发件人会收到系统退信。