Quản lý nhóm

Trang này mô tả cách quản lý Nhóm trên Google bằng Directory API:

Tạo nhóm
Cập nhật mộ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 một miền hoặc tài khoản
Truy xuất tất cả các nhóm của một thành viên
Truy xuất tất cả các bí danh 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à thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Bạn có thể tạo một nhóm cho bất kỳ miền nào được liên kết với tài khoản. Để biết các thuộc tính của chuỗi truy vấn, yêu cầu và 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ã trạng thái HTTP 201 và các thuộc tính cho nhóm mới.

Cập nhật mộ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 thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. groupKey là địa chỉ email của nhóm, địa chỉ email của bất kỳ email đại diện nào của nhóm hoặc id duy nhất của nhóm. Để biết 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 sử dụng địa chỉ email của nhóm làm khoá cho dữ liệu liên tục, 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à Nhóm bán hàng ở Châu Á – Thái Bình Dương:

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 mới trong yêu cầu của mình. Bạn không cần nhập tất cả các thuộc tính của nhóm trong yêu cầu.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 201 và các thuộc tính cho 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 một bí danh nhóm, hãy sử dụng yêu cầu POST sau đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu. groupKey là địa chỉ email của nhóm, địa chỉ email của email đại diện của nhóm hoặc id duy nhất của nhóm. Để biết 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

Nói chung, Google không khuyến khích bạn sử dụng địa chỉ email của nhóm làm khoá cho dữ liệu liên tục 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 biệt hiệu cho một nhóm. groupKey là id duy nhất của nhóm, được biểu thị bằng 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ã trạng thái HTTP 201 và các thuộc tính cho 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ầu GET sau đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu. groupKey là địa chỉ email của nhóm, địa chỉ email của email đại diện của nhóm hoặc id duy nhất của nhóm. Để biết 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

Nói chung, Google không khuyến khích bạn sử dụng địa chỉ email của nhóm làm khoá cho dữ liệu liên tục 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ã trạng thái HTTP 200 và 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 một 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à thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu. Để biết các thuộc tính của chuỗi truy vấn, yêu cầu và phản hồi, hãy xem phương thức groups.list. Để dễ đọc, ví dụ này sử dụng dấu xuống 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 miền.
Tất cả các nhóm cho tài khoản: Sử dụng đối số customer với my_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ỗi my_customer để biểu thị customerId của tài khoản. Nếu bạn là đại lý truy cập vào tài khoản của khách hàng được bán lại, hãy sử dụng customerId 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 một miền. Phản hồi nhận được có giá trị customerId.
Sử dụng cả đối số domain và customer: Directory API trả về tất cả các nhóm cho domain.
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 được liên kết với my_customer. Đây là tài khoản customerId của quản trị viên đưa ra yêu cầu.
Sử dụng cả đối số customer và userKey: Directory API sẽ trả về lỗi. Bạn phải đưa ra 2 yêu cầu riêng biệt bằng các đối số này.

Trong ví dụ sau, một quản trị viên tài khoản sử dụng my_customer để yêu cầu danh sách 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ề trên mỗi trang phản hồi là 2. Có một nextPageToken cho danh sách người dùng tiếp theo 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ã 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 của 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 thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Để dễ đọc, ví dụ này sử dụng dấu xuống 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 đại diện của người dùng, địa chỉ email chính của nhóm, địa chỉ email đại diện của nhóm hoặc id duy nhất của người dùng. Bạn có thể tìm thấy id này bằng cách sử dụng Thao tác truy xuất 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.
Sử dụng chuỗi truy vấn pageToken cho các phản hồi có số lượng lớn nhóm. Trong trường hợp phân trang, phản hồi sẽ trả về thuộc tính nextPageToken. Thuộc tính này cung cấp mã thông báo cho trang kết quả phản hồi tiếp theo. Yêu cầu tiếp theo của bạn sẽ sử dụng mã truy cập này làm giá trị chuỗi truy vấn pageToken.
Sử dụng cả đối số customer và userKey: Directory API sẽ trả về lỗi. Bạn phải đưa ra 2 yêu cầu riêng biệt bằng các đối số này.

Để biết 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ã trạng thái HTTP 200 và danh sách thông tin về thành viên:

Tất cả các nhóm mà một thành viên có gói thuê bao (kể cả các nhóm 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 của địa chỉ email của từng nhóm.
Trong nội dung phản hồi, id là mã nhận dạng riêng biệt của nhóm.
Trong phản hồi, danh sách một nhóm bên ngoài miền của người dùng không bao gồm các biệt hiệu 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"
     }
  ],
   "nextPageToken": "NNNNN"
}

Truy xuất tất cả các bí danh nhóm

Để truy xuất tất cả các bí danh của một nhóm, hãy dùng yêu cầu GET sau đây và thêm thông tin uỷ quyền như 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ỳ địa chỉ email đại diện nào của nhóm. Để biết 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ã trạng thái HTTP 201 và danh sách các biệt hiệu của nhóm.

Xoá bí danh nhóm

Để xoá biệt hiệu của một nhóm, hãy sử dụng yêu cầu DELETE sau đây và thêm thông tin uỷ quyền như 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ỳ địa chỉ email đại diện nào của nhóm. aliasId là bí danh đang bị xoá. Để biết 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ã trạng thái HTTP 201.

Xoá nhóm

Để xoá một nhóm, hãy dùng yêu cầu DELETE sau đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu. 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ã trạng thái HTTP 200.

Khi một nhóm bị xoá, những điều sau đây sẽ xảy ra:

Tất cả thành viên của nhóm đều bị xoá. Tài khoản người dùng của thành viên sẽ không bị xoá.
Kho lưu trữ của nhóm sẽ bị xoá.
Tin nhắn gửi đến địa chỉ của nhóm đã bị xoá sẽ không được gửi đi. Thay vào đó, người gửi sẽ nhận được một thư bị trả lại.