本頁面說明如何使用 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
一般來說,我們不建議使用群組的電子郵件地址做為永久資料的金鑰,因為電子郵件地址可能會有所變動。
下列 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
一般來說,我們不建議使用群組的電子郵件地址做為永久資料的金鑰,因為電子郵件地址可能會有所變動。
在以下範例中,專屬的 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
狀態碼。
刪除群組後,會發生下列情況:
- 所有群組成員都會遭到刪除。系統不會刪除成員的使用者帳戶。
- 已刪除群組封存內容。
- 寄給已刪除群組的郵件不會送達。而會傳送退件通知給寄件者。