管理群组

本页面介绍了如何使用 Directory API 管理 Google 群组：

  • 创建群组
  • 更新群组
  • 添加群组别名
  • 检索群组
  • 检索域或账号的所有群组
  • 检索成员的所有群组
  • 检索所有群组别名
  • 删除群组别名
  • 删除群组

创建群组

如需创建群组，请使用以下 POST 请求并添加授权 具体说明 向请求授权。 您可以为与账号关联的任何网域创建群组。对于查询字符串，请求、 和响应属性，请参阅 groups.insert 方法。 

POST https://admin.googleapis.com/admin/directory/v1/groups

以下 JSON 请求展示了用于创建群组的示例请求正文。群组的电子邮件地址 地址为 [email protected]： 

{
   "email": "[email protected]",
   "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，该组的 亚太地区销售组： 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "[email protected]",
    "name": "APAC Sales Group"
}

对于更新请求，您只需在请求中提交更新后的信息即可。你不会 需要在请求中输入组的所有属性

成功的响应会返回 HTTP 201 状态代码 以及新组的属性： 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "[email protected]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[email protected]"
     }
    ],
    "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": "[email protected]"
}

成功的响应会返回 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": "[email protected]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[email protected]"
     }
    ],
    "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": "[email protected]",
      "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": "[email protected]",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "[email protected]"
       }
      ],
      "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": "[email protected]",
      "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 状态代码。

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

  • 该群组的所有成员都会被删除。系统不会删除成员的用户账号。
  • 群组归档会被删除。
  • 系统不会递送发送到已删除群组地址的邮件。而是会收到 退回邮件。