管理群组

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

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 状态代码。

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

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