Trang này trình bày cách quản lý Google Groups bằng API thư mục:
- Tạo nhóm
- Cập nhật nhóm
- Thêm bí danh nhóm
- Truy xuất một nhóm
- Truy xuất tất cả các nhóm cho miền hoặc tài khoản
- Truy xuất tất cả các nhóm cho một thành viên
- Truy xuất tất cả email đại diện của nhóm
- Xoá bí danh nhóm
- Xoá nhóm
Tạo nhóm
Để tạo một nhóm, hãy sử dụng yêu cầu POST
sau đây và bao gồm quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu.
Bạn có thể tạo nhóm cho bất kỳ miền nào liên kết với tài khoản. Đối với các chuỗi truy vấn, yêu cầu và thuộc tính phản hồi, hãy xem phương thức groups.insert
.
POST https://admin.googleapis.com/admin/directory/v1/groups
Yêu cầu JSON sau đây cho thấy một nội dung yêu cầu mẫu tạo một nhóm. Địa chỉ email của nhóm là sales_group@example.com:
{ "email": "sales_group@example.com", "name": "Sales Group", "description": "This is the Sales group." }
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 201
và các thuộc tính của nhóm mới.
Cập nhật nhóm
Để cập nhật chế độ cài đặt của một nhóm, hãy sử dụng yêu cầu PUT
sau đây và thêm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép.
groupKey
là địa chỉ email của nhóm, bất kỳ địa chỉ email nào của bí danh nhóm, hoặc id
duy nhất của nhóm. Đối với các chuỗi truy vấn, yêu cầu và thuộc tính phản hồi, hãy xem phương thức groups.update
.
PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Nhìn chung, bạn không nên dùng địa chỉ email của nhóm làm khoá cho dữ liệu cố định vì địa chỉ email có thể thay đổi.
Trong ví dụ sau, groupKey
duy nhất là nnn
và tên của nhóm là APAC Sales Group:
PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{ "email": "sales_group@example.com", "name": "APAC Sales Group" }
Đối với yêu cầu cập nhật, bạn chỉ cần gửi thông tin đã cập nhật trong yêu cầu. Bạn không cần phải nhập tất cả thuộc tính của nhóm vào yêu cầu.
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 201
và các thuộc tính của nhóm mới:
{ "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" } ] }
Thêm bí danh nhóm
Để thêm email đại diện của nhóm, hãy sử dụng yêu cầu POST
sau đây và thêm quyền uỷ quyền được mô tả trong phần Uỷ quyền cho yêu cầu.
groupKey
là địa chỉ email của nhóm, bất kỳ địa chỉ email nào của bí danh nhóm, hoặc id
duy nhất của nhóm. Đối với các chuỗi truy vấn, yêu cầu và thuộc tính phản hồi, hãy xem tài nguyên groups
.
POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
Nhìn chung, bạn không nên dùng địa chỉ email của nhóm làm khoá cho dữ liệu cố định vì địa chỉ email có thể thay đổi.
Yêu cầu JSON sau đây cho thấy một yêu cầu mẫu để tạo email đại diện của một nhóm. groupKey
là id
duy nhất của nhóm được biểu thị bởi NNNN
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{ "alias": "best_sales_group@example.com" }
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 201
và các thuộc tính của bí danh nhóm mới.
Truy xuất một nhóm
Để truy xuất một nhóm, hãy sử dụng yêu cầuGET
sau đây và đưa vào hoạt động uỷ quyền như mô tả trong phần Uỷ quyền cho yêu cầu.
groupKey
là địa chỉ email của nhóm, bất kỳ địa chỉ email nào của bí danh nhóm, hoặc id
duy nhất của nhóm. Đối với các chuỗi truy vấn, yêu cầu và thuộc tính phản hồi, hãy xem phương thức groups.get
.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Nhìn chung, bạn không nên dùng địa chỉ email của nhóm làm khoá cho dữ liệu cố định vì địa chỉ email có thể thay đổi.
Trong ví dụ sau, mã nhận dạng groupKey
duy nhất là nnnn
:
GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 200
và các chế độ cài đặt của nhóm:
{ "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" } ] }
Truy xuất tất cả các nhóm cho miền hoặc tài khoản
Để truy xuất tất cả các nhóm cho một miền hoặc tài khoản cụ thể, hãy sử dụng yêu cầu GET
sau đây và bao gồm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. Đối với các chuỗi truy vấn, yêu cầu và thuộc tính phản hồi, hãy xem phương thức groups.list
.
Để dễ đọc, ví dụ này sử dụng phương thức trả về dòng:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name &customer=my_customer or customerId&pageToken=pagination token &maxResults=max results
Khi truy xuất tất cả các nhóm cho một miền hoặc tài khoản, hãy cân nhắc những điều sau:
- Tất cả các nhóm cho một miền phụ: Sử dụng đối số
domain
với tên của miền. - Tất cả các nhóm của tài khoản: Sử dụng đối số
customer
vớimy_customer
hoặc giá trịcustomerId
của tài khoản. Là quản trị viên tài khoản, hãy sử dụng chuỗimy_customer
để biểu thịcustomerId
của tài khoản. Nếu bạn là đại lý và có quyền truy cập vào tài khoản của khách hàng được bán lại, hãy sử dụngcustomerId
của tài khoản được bán lại. Đối với giá trịcustomerId
, hãy sử dụng tên miền chính của tài khoản trong yêu cầu của thao tác Truy xuất tất cả người dùng trong miền. Phản hồi thu được có giá trịcustomerId
. - Sử dụng cả hai đối số
domain
vàcustomer
: API Thư mục trả về tất cả các nhóm chodomain
. - Không sử dụng các đối số
domain
vàcustomer
: API Thư mục trả về tất cả các nhóm cho tài khoản liên kết vớimy_customer
. Đây là tài khoảncustomerId
của quản trị viên đưa ra yêu cầu. - Sử dụng cả hai đối số
customer
vàuserKey
: API Thư mục sẽ trả về lỗi. Bạn phải thực hiện hai yêu cầu riêng biệt với các đối số này.
Trong ví dụ sau, quản trị viên tài khoản sử dụng my_customer
để yêu cầu liệt kê tất cả các nhóm của một tài khoản:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2
Trong ví dụ sau, yêu cầu của quản trị viên đại lý sẽ trả về tất cả các nhóm cho tài khoản được bán lại
có customerId C03az79cb
. Số kết quả tối đa được trả về cho mỗi trang phản hồi là 2.
Có một nextPageToken
cho danh sách người dùng theo dõi trong phản hồi này:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 200
và các nhóm theo thứ tự bảng chữ cái của email nhóm:
{ "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" }
Truy xuất tất cả các nhóm cho một thành viên
Để truy xuất tất cả các nhóm mà một thành viên có gói thuê bao, hãy sử dụng yêu cầu GET
sau đây và thêm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. Để dễ đọc, ví dụ này sử dụng phương thức trả về dòng:
GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key ?pageToken=pagination token &maxResults=maximum results per response page
- Thành viên có thể là người dùng hoặc nhóm.
userKey
có thể là địa chỉ email chính của người dùng, địa chỉ email bí danh của người dùng, địa chỉ email chính của nhóm, bí danh email của nhóm hoặcid
duy nhất của người dùng bằng cách sử dụng tính năng Truy xuất thao tác của người dùng.- Người dùng hoặc nhóm được chỉ định trong
userKey
phải thuộc miền của bạn. - Dùng chuỗi truy vấn
pageToken
cho các phản hồi có nhiều nhóm. Trong trường hợp phân trang, phản hồi sẽ trả về thuộc tínhnextPageToken
. Thuộc tính này cung cấp mã thông báo cho trang tiếp theo của kết quả phản hồi. Yêu cầu tiếp theo của bạn sẽ sử dụng mã thông báo này làm giá trị chuỗi truy vấnpageToken
. - Sử dụng cả hai đối số
customer
vàuserKey
: API Thư mục sẽ trả về lỗi. Bạn phải thực hiện hai yêu cầu riêng biệt với các đối số này.
Đối với các thuộc tính yêu cầu và phản hồi, hãy xem phương thức groups.list
.
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 200 và danh sách thông tin thành viên:
- Tất cả các nhóm mà thành viên có gói thuê bao, bao gồm cả các nhóm từ bên ngoài miền của người dùng, đều được trả về.
- Các nhóm được trả về theo thứ tự bảng chữ cái trong địa chỉ email của mỗi nhóm.
- Trong nội dung phản hồi,
id
là mã nhận dạng duy nhất của nhóm. - Trong phản hồi này, trang thông tin về một nhóm ở bên ngoài miền của người dùng không bao gồm email đại diện của nhóm bên ngoài đó.
{ "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" }
Truy xuất tất cả email đại diện của nhóm
Để truy xuất tất cả các bí danh của một nhóm, hãy sử dụng yêu cầuGET
sau đây và đưa vào quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. groupKey
có thể là địa chỉ email chính của nhóm, id
duy nhất của nhóm hoặc bất kỳ email đại diện nào của nhóm. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem tài nguyên groups
.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 201
và danh sách các email đại diện của nhóm.
Xoá bí danh nhóm
Để xoá bí danh của một nhóm, hãy sử dụng yêu cầuDELETE
sau đây và đưa vào quyền được mô tả trong phần Uỷ quyền yêu cầu.
groupKey
có thể là địa chỉ email chính của nhóm, id
duy nhất của nhóm hoặc bất kỳ email đại diện nào của nhóm. aliasId
là bí danh bị xoá. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem tài nguyên groups
:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 201
.
Xoá nhóm
Để xoá một nhóm, hãy sử dụng yêu cầu DELETE
sau đây và thêm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép.
groupKey
là id
duy nhất của nhóm:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Ví dụ: yêu cầu DELETE
này sẽ xoá nhóm có nhóm nnnn
id
:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn
Phản hồi thành công sẽ trả về một mã trạng thái HTTP 200
.
Khi bạn xoá một nhóm, những điều sau sẽ xảy ra:
- Tất cả thành viên của nhóm đã bị xoá. Tài khoản người dùng của thành viên đó sẽ không bị xoá.
- Tệp lưu trữ nhóm đã bị xoá.
- Thư gửi đến địa chỉ của nhóm đã xóa sẽ không được gửi đi. Thay vào đó, người gửi sẽ nhận được một thư trả lại.