管理群组

本页介绍了如何使用 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

一般来说，我们建议不要使用群组的电子邮件地址作为持久性数据的键，因为电子邮件地址可能会发生变化。

一般来说，我们建议不要使用群组的电子邮件地址作为持久性数据的键，因为电子邮件地址可能会发生变化。

在以下示例中，唯一 groupKey 为 nnn，群组名称为“亚太销售群组”： 

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，该 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"
     }
  ],
   "nextPageToken": "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 状态代码。

删除群组后，会发生以下情况：

  • 系统会删除群组的所有成员。系统不会删除成员的用户账号。
  • 群组归档已被删除。
  • 发送到已删除群组的电子邮件地址的邮件将无法递送。发件人会收到系统退信。