管理群组

本页面介绍如何使用 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 建议不要将群组的电子邮件地址用作持久性数据的密钥,因为电子邮件地址随时可能更改。

在以下示例中,唯一的 groupKeynnn,该群组的名称为 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 值。
  • 同时使用 domaincustomer 参数:Directory API 会返回 domain 的所有群组。
  • 不使用 domaincustomer 参数:Directory API 会返回与 my_customer 关联的帐号的所有群组。这是发出请求的管理员的帐号 customerId
  • 同时使用 customeruserKey 参数: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 查询字符串值。
  • 同时使用 customeruserKey 参数: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 状态代码

删除群组后,会出现以下情况:

  • 群组中的所有成员都会被删除。系统不会删除成员的用户帐号。
  • 此群组归档已删除。
  • 无法递送发送至已删除群组地址的邮件。相反,发件人会收到系统退信。