管理群組

本頁說明如何使用 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，群組名稱為「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"
     }
  ],
   "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

成功的回應會傳回 HTTP201 狀態碼。

刪除群組

如要刪除群組，請使用下列 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

成功的回應會傳回 HTTP200 狀態碼。

刪除群組後，會發生下列情況：

  • 所有群組成員都會遭到刪除，成員的使用者帳戶不會遭到刪除。
  • 系統會刪除群組封存內容。
  • 傳送給已刪除群組地址的郵件無法送達。而是傳送退信通知給寄件者。