Directory API:群组

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

创建组

如需创建群组,请使用以下 POST 请求并添加授权请求中所述的授权。您可以为与帐号关联的任何网域创建群组。如需了解查询字符串、请求和响应属性,请参阅 API 参考文档

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

JSON 请求

以下 JSON 请求显示了用于创建组的示例请求正文。该群组的电子邮件地址为 sales_group@example.com:

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

成功的响应将返回一个 HTTP 201 状态代码。响应将返回状态代码以及新组的属性。

更新群组

如需更新群组的设置,请使用以下 PUT 请求并添加授权请求中所述的授权。groupKey 是群组的电子邮件地址、群组别名的任何电子邮件地址或群组的唯一 id。如需了解查询字符串、请求和响应属性,请参阅 API 参考文档

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

一般而言,Google 建议不要将群组的电子邮件地址用作永久性数据的密钥,因为电子邮件地址可能会发生变化。

JSON 请求

在下面的示例中,唯一 groupKey 为 &nn39; 且群组的名称已更改为亚太地区的销售组:

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

对于更新请求,您只需在请求中提交更新后的信息即可。您无需在请求中输入组的所有属性。

JSON 响应

成功的响应将返回一个 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。如需了解查询字符串、请求和响应属性,请参阅 API 参考文档

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

一般而言,Google 建议不要将群组的电子邮件地址用作永久性数据的密钥,因为电子邮件地址可能会发生变化。

JSON 请求

以下 JSON 请求显示创建群组别名的示例请求。groupKey 是由 NNNN 表示的唯一群组 id
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{
    "alias": "best_sales_group@example.com"
}

JSON 响应

成功的响应将返回一个 HTTP 201 状态代码。响应将返回状态代码以及新群组别名的属性。

检索群组

如需检索群组,请使用以下 GET 请求并添加授权请求中所述的授权。groupKey 是群组的电子邮件地址、群组别名的任何电子邮件地址或群组的唯一 id。如需了解查询字符串、请求和响应属性,请参阅 API 参考文档
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

一般而言,Google 建议不要将群组的电子邮件地址用作永久性数据的密钥,因为电子邮件地址可能会发生变化。

在下面的示例中,唯一的 groupKey ID 为 &nn39;nnnn':

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

JSON 响应

成功的响应将返回一个 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 请求并添加授权请求中所述的授权。如需了解查询字符串、请求和响应属性,请参阅 API 参考文档。为方便阅读,此示例使用代码行返回:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

检索时:

  • 子网域的所有群组 - 使用带有网域名称的 domain 参数。
  • 帐号的所有群组 - 使用值为 my_customer 或帐号的 customerIdcustomer 参数。作为帐号管理员,请使用字符串 my_customer 代表您帐号的“customerId”。如果您是转销商且访问的是转销商的客户,请使用转销商帐号的customerId。对于 customerId 值,请在检索网域中的所有用户操作的请求中使用帐号的域名。生成的响应具有 customerId 值。
  • 同时使用 domaincustomer 参数 - API 会返回 domain 的所有组。
  • 不使用 domaincustomer 参数 - API 会返回与 my_customer 相关联的帐号的所有群组。这是发出 API 请求的管理员的帐号 customerId

在此示例中,帐号管理员使用 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

JSON 响应

成功的响应将返回一个 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 查询字符串值。

如需了解请求和响应属性,请参阅 API 参考文档

JSON 响应

成功的响应将返回一个 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 或任何群组别名的电子邮件地址。如需了解请求和响应属性,请参阅 API 参考文档

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

成功的响应将返回一个 HTTP 201 状态代码。响应将返回状态代码以及状态代码组列表。

删除群组别名

要删除群组的别名,请使用以下 DELETE 请求,并包含授权请求中所述的授权。groupKey 可以是群组的主电子邮件地址、群组的唯一 id 或任何群组别名的电子邮件地址。aliasId 是要删除的别名。如需了解请求和响应属性,请参阅 API 参考文档

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

删除群组后:

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