Directory API cung cấp các phương thức lập trình để tạo, cập nhật và xoá người dùng. Bạn cũng có thể nhận thông tin về từng người dùng hoặc danh sách người dùng đáp ứng các tiêu chí cụ thể. Sau đây là ví dụ về một số thao tác cơ bản của người dùng.
Tạo tài khoản người dùng
Bạn có thể thêm tài khoản người dùng vào bất kỳ miền nào của tài khoản Google Workspace. Trước khi thêm tài khoản người dùng, hãy xác nhận quyền sở hữu miền.
Nếu đã nâng cấp tài khoản Gmail cá nhân lên tài khoản email doanh nghiệp có tên miền của riêng bạn, thì bạn sẽ không thể tạo tài khoản người dùng mới cho đến khi mở khoá các chế độ cài đặt bổ sung của Google Workspace. Để biết thông tin chi tiết, hãy xem bài viết Tài khoản email G Suite Business được cập nhật lên G Suite Basic.
Để tạo tài khoản người dùng bằng một trong các miền của bạn, 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 Tìm hiểu về việc xác thực và uỷ quyền. Bạn có thể xem các phạm vi hiện có cho API Thư mục trong danh sách phạm vi OAuth 2.0. Đối với các thuộc tính chuỗi truy vấn yêu cầu, hãy xem phương thức users.insert().
POST https://admin.googleapis.com/admin/directory/v1/users
Tất cả yêu cầu tạo đều yêu cầu bạn gửi thông tin cần thiết để thực hiện yêu cầu. Nếu bạn đang sử dụng thư viện ứng dụng, thì thư viện này sẽ chuyển đổi các đối tượng dữ liệu từ ngôn ngữ bạn chọn thành các đối tượng có định dạng dữ liệu JSON.
Yêu cầu JSON
JSON sau đây cho thấy một yêu cầu mẫu để tạo người dùng. Để biết danh sách đầy đủ các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
{
"primaryEmail": "[email protected]",
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
{
"type": "work",
"protocol": "gtalk",
"im": "[email protected]",
"primary": true
}
],
"emails": [
{
"address": "[email protected]",
"type": "home",
"customType": "",
"primary": true
}
],
"addresses": [
{
"type": "work",
"customType": "",
"streetAddress": "1600 Amphitheatre Parkway",
"locality": "Mountain View",
"region": "CA",
"postalCode": "94043"
}
],
"externalIds": [
{
"value": "12345",
"type": "custom",
"customType": "employee"
}
],
"organizations": [
{
"name": "Google Inc.",
"title": "SWE",
"primary": true,
"type": "work",
"description": "Software engineer"
}
],
"phones": [
{
"value": "+1 nnn nnn nnnn",
"type": "work"
}
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}
Nếu tốc độ truy vấn cho các yêu cầu tạo quá cao, bạn có thể nhận được phản hồi 503 HTTP từ máy chủ API cho biết rằng bạn đã vượt quá hạn mức. Nếu bạn nhận được những phản hồi này, hãy sử dụng thuật toán thời gian đợi luỹ thừa để thử lại các yêu cầu của bạn.
Sau đây là những điều cần lưu ý về tài khoản mới:
- Nếu Tài khoản Google đã mua giấy phép thư, thì tài khoản người dùng mới sẽ tự động được chỉ định một hộp thư. Có thể mất vài phút để hoàn tất và kích hoạt bài tập này.
- Dịch vụ API sẽ tự động bỏ qua việc chỉnh sửa trường chỉ có thể đọc trong yêu cầu, chẳng hạn như
isAdmin. - Số lượng miền tối đa được phép trong một tài khoản là 600 (1 miền chính + 599 miền bổ sung)
- Nếu người dùng không được chỉ định cho một đơn vị tổ chức cụ thể khi tạo tài khoản người dùng, thì tài khoản đó sẽ nằm trong đơn vị tổ chức cấp cao nhất. Đơn vị tổ chức của người dùng sẽ xác định những dịch vụ Google Workspace mà người dùng đó có quyền truy cập. Nếu người dùng được chuyển sang một tổ chức mới, thì quyền truy cập của người dùng sẽ thay đổi. Để biết thêm thông tin về cấu trúc tổ chức, hãy xem trung tâm trợ giúp dành cho quản trị viên. Để biết thêm thông tin về cách chuyển người dùng sang một tổ chức khác, hãy xem bài viết Cập nhật người dùng.
- Tài khoản người dùng mới phải có
password. Nếu bạn chỉ địnhhashFunction, thì mật khẩu phải là khoá băm hợp lệ. Nếu không được chỉ định, mật khẩu phải ở dạng văn bản thô và có từ 8 đến 100 ký tự ASCII. Để biết thêm thông tin, hãy xem Tài liệu tham khảo API. - Đối với người dùng sử dụng gói linh hoạt của Google Workspace, việc tạo người dùng bằng API này sẽ ảnh hưởng đến tài chính và sẽ dẫn đến việc tính phí vào tài khoản thanh toán của khách hàng. Để biết thêm thông tin, hãy xem phần Thông tin thanh toán qua API.
- Một tài khoản Google Workspace có thể bao gồm bất kỳ miền nào của bạn. Trong tài khoản nhiều miền, người dùng trong một miền có thể chia sẻ dịch vụ với người dùng trong các miền tài khoản khác. Để biết thêm thông tin về người dùng trong nhiều miền, hãy xem phần Thông tin về nhiều miền API.
- Có thể có tài khoản xung đột. Kiểm tra xem người mà bạn định thêm vào đã có Tài khoản Google hay chưa. Sau đó, hãy làm theo các bước để tránh xung đột với các tài khoản đó. Hãy xem bài viết Tìm và khắc phục tài khoản xung đột.
- Có thể có tài khoản khách truy cập. Nếu người dùng mời những người bên ngoài tổ chức của bạn và không có Tài khoản Google cộng tác trên Drive, thì họ sẽ nhận được tài khoản khách truy cập, theo định dạng tên_người_dùng_của_khách_truy_cập@miền_của_bạn. Nếu bạn thêm một người dùng có cùng tên người dùng với tài khoản khách truy cập, thì tài khoản đó sẽ được chuyển đổi thành tài khoản Google Workspace đầy đủ. Tài khoản này sẽ giữ nguyên quyền đối với tệp trên Drive. Xem bài viết Chia sẻ tài liệu với khách truy cập.
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các thuộc tính cho tài khoản người dùng mới.
Cập nhật tài khoản người dùng
Để cập nhật tài khoản người dùng, 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 Uỷ quyền yêu cầu. userKey có thể là địa chỉ email chính của người dùng, id người dùng duy nhất hoặc một trong các địa chỉ email đại diện của người dùng.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey
Cả nội dung yêu cầu và nội dung phản hồi đều chứa một thực thể của User. Tuy nhiên, Directory API hỗ trợ ngữ nghĩa bản vá, vì vậy, bạn chỉ cần gửi các trường đã cập nhật trong yêu cầu của mình.
Yêu cầu mẫu
Trong ví dụ bên dưới, givenName của người dùng là "Elizabeth" khi tài khoản người dùng được tạo và chỉ cung cấp địa chỉ email công việc.
{
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"emails": [
{
"address": "[email protected]",
"type": "work",
"primary": true
}
}
Yêu cầu bên dưới cập nhật givenName từ "Elizabeth" thành "Liz", đồng thời thêm địa chỉ email gia đình. Xin lưu ý rằng cả hai địa chỉ email đều được cung cấp đầy đủ vì trường này là một mảng.
PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]
{
"name": {
"givenName": "Liz",
},
"emails": [
{
"address": "[email protected]",
"type": "work",
"primary": true
},
{
"address": "[email protected]",
"type": "home"
}
]
}
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và tài nguyên User có các trường đã cập nhật.
Hãy lưu ý những điều sau khi cập nhật tên tài khoản của người dùng:
- Việc đổi tên tài khoản người dùng sẽ thay đổi địa chỉ email chính của người dùng và miền được dùng khi truy xuất thông tin của người dùng này. Trước khi đổi tên người dùng, bạn nên đăng xuất người dùng khỏi tất cả các phiên trình duyệt và dịch vụ.
- Quá trình đổi tên tài khoản người dùng có thể mất đến 10 phút để truyền tải trên tất cả các dịch vụ.
- Khi bạn đổi tên người dùng, tên người dùng cũ sẽ được giữ lại dưới dạng tên đại diện để đảm bảo việc gửi thư liên tục trong trường hợp có chế độ cài đặt chuyển tiếp email và không được dùng làm tên người dùng mới.
- Nhìn chung, bạn cũng không nên sử dụng địa chỉ email của người dùng làm khoá cho dữ liệu cố định vì địa chỉ email có thể thay đổi.
- Để biết danh sách đầy đủ các hiệu ứng của việc đổi tên người dùng trên các ứng dụng của Google Workspace, hãy xem Trung tâm trợ giúp dành cho quản trị viên.
Đặt người dùng làm quản trị viên
Để chuyển người dùng thành quản trị viên cấp cao, 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 yêu cầu. userKey có thể là địa chỉ email chính của người dùng, id người dùng duy nhất hoặc một trong các địa chỉ email đại diện của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API. Để biết thêm thông tin về quản trị viên cấp cao, hãy xem trung tâm trợ giúp dành cho quản trị viên.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin
Yêu cầu JSON
Trong ví dụ này, người dùng có userKey là [email protected] đã trở thành quản trị viên cấp cao:
POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/makeAdmin
{
"status": true
}
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200.
Quản lý mối quan hệ của người dùng
Directory API sử dụng trường relations để xác định các loại mối quan hệ khác nhau giữa người dùng. Trong môi trường doanh nghiệp, mọi người thường sử dụng trường này cho mối quan hệ giữa người quản lý và nhân viên cũng như trợ lý, nhưng trường này cũng hỗ trợ nhiều loại mối quan hệ khác. Mối quan hệ này sẽ hiển thị trong thẻ "Người liên quan" của người dùng trong mọi ứng dụng Google Workspace hỗ trợ thẻ này. Để biết ví dụ về vị trí hiển thị thẻ, hãy xem phần Thêm thông tin vào hồ sơ Danh bạ của người dùng.
Tạo mối quan hệ giữa người dùng
Bạn chỉ có thể xác định mối quan hệ theo một hướng, bắt đầu từ người dùng "sở hữu", có bản ghi bao gồm trường relations. type mô tả mối quan hệ của người khác với người dùng sở hữu. Ví dụ: trong mối quan hệ người quản lý – nhân viên, nhân viên là người dùng sở hữu và bạn thêm trường relations vào tài khoản của họ với loại manager. Đối với các loại được phép, hãy xem tài liệu tham khảo đối tượng User.
Thiết lập mối quan hệ bằng cách tạo hoặc cập nhật người dùng sở hữu bằng nội dung yêu cầu JSON bao gồm trường relations.
Bạn có thể tạo nhiều mối quan hệ trong một yêu cầu.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_1",
"type": "manager"
},
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "dotted_line_manager"
}
]
}
Cập nhật hoặc xoá mối quan hệ
Bạn chỉ có thể cập nhật toàn bộ trường relations – bạn không thể thay đổi loại mối quan hệ hoặc xoá từng người được liệt kê. Trong ví dụ trên, để xoá mối quan hệ người quản lý hiện có và đặt người quản lý có đường kẻ chấm thành người quản lý của người dùng sở hữu, hãy cập nhật tài khoản của người dùng sở hữu bằng tất cả các giá trị của trường mà bạn muốn.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "manager"
}
]
}
Để xoá tất cả mối quan hệ của người dùng sở hữu, hãy đặt relations thành trống:
{
"relations": []
}
Truy xuất người dùng
Để truy xuất người dùng, 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. userKey có thể là địa chỉ email chính của người dùng, id người dùng duy nhất hoặc một trong các địa chỉ email đại diện của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey
Ví dụ này trả về các thuộc tính tài khoản người dùng cho người dùng có địa chỉ email chính hoặc địa chỉ email đại diện là [email protected]:
GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các thuộc tính cho tài khoản người dùng.
{
"kind": "directory#user",
"id": "the unique user id",
"primaryEmail": "[email protected]",
"name": {
"givenName": "Liz",
"familyName": "Smith",
"fullName": "Liz Smith"
},
"isAdmin": true,
"isDelegatedAdmin": false,
"lastLoginTime": "2013-02-05T10:30:03.325Z",
"creationTime": "2010-04-05T17:30:04.325Z",
"agreedToTerms": true,
"hashFunction": "SHA-1",
"suspended": false,
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
{
"type": "work",
"protocol": "gtalk",
"im": "[email protected]",
"primary": true
}
],
"emails": [
{
"address": "[email protected]",
"type": "home",
"customType": "",
"primary": true
}
],
"addresses": [
{
"type": "work",
"customType": "",
"streetAddress": "1600 Amphitheatre Parkway",
"locality": "Mountain View",
"region": "CA",
"postalCode": "94043"
}
],
"externalIds": [
{
"value": "employee number",
"type": "custom",
"customType": "office"
}
],
"organizations": [
{
"name": "Google Inc.",
"title": "SWE",
"primary": true,
"customType": "",
"description": "Software engineer"
}
],
"phones": [
{
"value": "+1 nnn nnn nnnn",
"type": "work"
}
],
"aliases": [
"[email protected]",
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "corp/engineering",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
}
Truy xuất tất cả người dùng trong một miền
Để truy xuất tất cả người dùng trong cùng một miền, 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 các dòng trả về:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=email, givenName, or familyName:the query's value*
Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
Nội dung phản hồi JSON
Trong ví dụ này, tất cả người dùng trong miền example.com sẽ được trả về với tối đa 2 miền người dùng trên mỗi trang phản hồi. Có một nextPageToken cho danh sách tiếp theo của người dùng trong phản hồi này. Theo mặc định, hệ thống sẽ trả về danh sách 100 người dùng theo thứ tự bảng chữ cái của địa chỉ email của người dùng:
GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về 2 tài khoản người dùng trong miền example.com (maxResults=2):
{
"kind": "directory#users",
"users": [
{
"kind": "directory#user",
"id": "the unique user id",
"primaryEmail": "[email protected]",
"name": {
"givenName": "Liz",
"familyName": "Smith",
"fullName": "Liz Smith"
},
"isAdmin": true,
"isDelegatedAdmin": false,
"lastLoginTime": "2013-02-05T10:30:03.325Z",
"creationTime": "2010-04-05T17:30:04.325Z",
"agreedToTerms": true,
"hashFunction": "SHA-1",
"suspended": false,
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
{
"type": "work",
"protocol": "gtalk",
"im": "[email protected]",
"primary": true
}
],
"emails": [
{
"address": "[email protected]",
"type": "work",
"customType": "",
"primary": true
}
],
"addresses": [
{
"type": "work",
"customType": "",
"streetAddress": "1600 Amphitheatre Parkway",
"locality": "Mountain View",
"region": "CA",
"postalCode": "94043"
}
],
"externalIds": [
{
"value": "employee number",
"type": "custom",
"customType": "office"
}
],
"organizations": [
{
"name": "Google Inc.",
"title": "SWE",
"primary": true,
"customType": "",
"description": "Software engineer"
}
],
"phones": [
{
"value": "+1 nnn nnn nnnn",
"type": "work"
}
],
"aliases": [
"[email protected]",
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "corp/engineering",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
},
{
"kind": "directory#user",
"id": "user unique ID",
"primaryEmail": "[email protected]",
"name": {
"givenName": "admin",
"familyName": "two",
"fullName": "admin two"
},
"isAdmin": true,
"isDelegatedAdmin": true,
"lastLoginTime": "2013-02-05T10:30:03.325Z",
"creationTime": "2010-04-05T17:30:04.325Z",
"agreedToTerms": true,
"hashFunction": "SHA-1",
"suspended": true,
"suspensionReason": "ADMIN",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"emails": [
{
"address": "[email protected]",
"type": "work",
"customType": "",
"primary": true
}
],
"externalIds": [
{
"value": "contractor license number",
"type": "custom",
"customType": "work"
}
],
"aliases": [
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "corp/engineering",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
}
],
"nextPageToken": "next page token"
}
Truy xuất tất cả người dùng tài khoản
Để truy xuất tất cả người dùng trong một tài khoản có thể bao gồm nhiều miền, 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 các dòng trả về:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=user attributes
- Chuỗi truy vấn
customerlà giá trịmy_customerhoặccustomerId. - Sử dụng chuỗi
my_customerđể biểu thịcustomerIdcủa tài khoản. - Là quản trị viên của đại lý, hãy sử dụng
customerIdcủa khách hàng đã bán lại. Đối vớicustomerId, 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 thu được có giá trịcustomerId. - Chuỗi truy vấn
orderBy(không bắt buộc) xác định xem danh sách được sắp xếp theo địa chỉ email chính, họ hoặc tên của người dùng hay không. Khi sử dụngorderBy, bạn cũng có thể sử dụng chuỗi truy vấnsortOrderđể liệt kê kết quả theo thứ tự tăng dần hoặc giảm dần. - Chuỗi truy vấn
querykhông bắt buộc cho phép tìm kiếm trên nhiều trường trong hồ sơ người dùng, bao gồm cả trường cốt lõi và trường tuỳ chỉnh. Hãy xem phần Tìm người dùng để biết ví dụ.
Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
Trong ví dụ này, quản trị viên tài khoản yêu cầu trả về tất cả người dùng trong tài khoản, mỗi trang phản hồi trả về một mục nhập người dùng. nextPageToken chuyển đến trang kết quả tiếp theo:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1
Trong ví dụ này, quản trị viên đại lý đang yêu cầu tất cả người dùng trong một tài khoản được bán lại có giá trị customerId là C03az79cb.
GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về tất cả người dùng trong tài khoản này:
{
"kind": "directory#users",
"users": [
{
"kind": "directory#user",
"id": "the unique user id",
"username": "[email protected]",
"name": {
"givenName": "admin",
"familyName": "two",
"fullName": "admin two"
},
"isAdmin": true,
"isDelegatedAdmin": true,
"lastLoginTime": "2013-02-05T10:30:03.325Z",
"creationTime": "2010-04-05T17:30:04.325Z",
"agreedToTerms": true,
"hashFunction": "SHA-1",
"suspended": false,
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"emails": [
{
"address": "[email protected]",
"type": "work",
"customType": "",
"primary": true
}
],
"externalIds": [
{
"value": "employee number",
"type": "custom",
"customType": "office"
}
],
"aliases": [
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "/",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
},
{
"kind": "directory#user",
"id": "the unique user id",
"username": "[email protected]",
"name": {
"givenName": "Elizabeth",
"familyName": "Smith",
"fullName": "Elizabeth Smith"
},
"isAdmin": false,
"isDelegatedAdmin": false,
"lastLoginTime": "1336509883546",
"creationTime": "1404802800000",
"agreedToTerms": false,
"hashFunction": "SHA-1",
"suspended": false,
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"emails": [
{
"address": "[email protected]",
"type": "home",
"customType": "",
"primary": true
}
],
"externalIds": [
{
"value": "employee number",
"type": "custom",
"customType": "bank"
}
],
"relations": [
{
"value": "liz",
"type": "friend",
"customType": ""
}
],
"aliases": [
"[email protected]",
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "/",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
},
{
"kind": "directory#user",
"id": "the unique user id",
"username": "[email protected]",
"name": {
"givenName": "Tester",
"familyName": "Three",
"fullName": "Tester Three"
},
"isAdmin": false,
"isDelegatedAdmin": false,
"lastLoginTime": "1336509883546",
"creationTime": "1404802800000",
"agreedToTerms": true,
"hashFunction": "SHA-1",
"suspended": false,
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"emails": [
{
"address": "[email protected]",
"type": "work",
"customType": "",
"primary": true
}
],
"externalIds": [
{
"value": "employee number",
"type": "custom",
"customType": "office"
}
],
"aliases": [
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "/",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
},
{
"kind": "directory#user",
"id": "the unique user id",
"username": "[email protected]",
"name": {
"givenName": "Admin",
"familyName": "Work",
"fullName": "Admin Work"
},
"isAdmin": true,
"isDelegatedAdmin": true,
"lastLoginTime": "1336509883546",
"creationTime": "1404802800000",
"agreedToTerms": true,
"hashFunction": "SHA-1",
"suspended": false,
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"emails": [
{
"address": "[email protected]",
"type": "work",
"customType": "",
"primary": true
}
],
"externalIds": [
{
"value": "employee number",
"type": "custom",
"customType": "office"
}
],
"aliases": [
"[email protected]"
],
"nonEditableAliases": [
"[email protected]"
],
"customerId": "C03az79cb",
"orgUnitPath": "/",
"isMailboxSetup": true,
"includeInGlobalAddressList": true
}
],
"nextPageToken": "NNNNN"
}
Truy xuất người dùng đã xoá gần đây
Để truy xuất tất cả người dùng đã bị xoá trong vòng 20 ngày qua khỏi một tài khoản hoặc khỏi một trong các miền của tài khoản, hãy sử dụng các yêu cầu GET sau và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Để huỷ xoá người dùng, hãy xem bài viết Huỷ xoá người dùng.
Để truy xuất những người dùng đã bị xoá trong vòng 20 ngày qua khỏi miền chính hoặc miền con của tài khoản, hãy sử dụng yêu cầu GET sau. Chuỗi truy vấn domain là tên miền chính của miền. Đối với các thuộc tính yêu cầu và phản hồi của người dùng, hãy xem Tài liệu tham khảo API. Để dễ đọc, ví dụ này sử dụng các dòng trả về:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &showDeleted=trueNếu một tài khoản có nhiều miền, bạn có thể truy xuất người dùng đã bị xoá trong vòng 20 ngày qua trên toàn bộ tài khoản bằng cách sử dụng yêu cầu
GET sau đây. Để dễ đọc, ví dụ này sử dụng các dòng trả về:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page&showDeleted=true
- Chuỗi truy vấn
customerlà giá trịmy_customerhoặccustomerId. - Là quản trị viên tài khoản, hãy sử dụng chuỗi
my_customerđể biểu thịcustomerIdcủa tài khoản. - Là quản trị viên của đại lý, hãy sử dụng
customerIdcủa khách hàng đã bán lại. Đối vớicustomerId, 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 thu được có giá trịcustomerId.
Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
Trong ví dụ này, quản trị viên tài khoản đang yêu cầu tất cả người dùng đã xoá trong tài khoản:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true
Nội dung phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về tất cả người dùng tài khoản đã bị xoá trong vòng 20 ngày qua:
{
"kind": "directory#users",
"users": [
{
"kind": "directory#user",
"id": "the unique user id",
"primaryEmail": "[email protected]"
},
{
"kind": "directory#user",
"id": "the unique user id",
"primaryEmail": "[email protected]"
}
],
"nextPageToken": "token for next page of deleted users"
}
Truy xuất ảnh của người dùng
API này truy xuất một hình thu nhỏ của ảnh, tức là ảnh hồ sơ mới nhất trên Google. Để truy xuất ảnh mới nhất của người dùng, 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. userKey có thể là địa chỉ email chính của người dùng, id của người dùng hoặc bất kỳ email đại diện nào của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
Trong ví dụ này, hệ thống sẽ trả về ảnh mới nhất của [email protected]:
GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
Phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200.
{
"kind": "directory#user#photo",
"id": "the unique user id",
"primaryEmail": "[email protected]",
"mimeType": "the photo mime type",
"height": "the photo height in pixels",
"width": "the photo width in pixels",
"photoData": "web safe base64 encoded photo data"
}
Phương thức mã hoá base64 an toàn cho web của API đối với ảnh tương tự như RFC 4648 "base64url". Điều này có nghĩa là:
- Ký tự gạch chéo (/) được thay thế bằng ký tự dấu gạch dưới (_).
- Ký tự dấu cộng (+) được thay thế bằng ký tự dấu gạch nối (-).
- Ký tự dấu bằng (=) được thay thế bằng dấu hoa thị (*).
- Để tạo khoảng đệm, ký tự dấu chấm (.) được sử dụng thay vì định nghĩa baseURL RFC-4648 sử dụng dấu bằng (=) để tạo khoảng đệm. Việc này được thực hiện để đơn giản hoá việc phân tích cú pháp URL.
- Bất kể kích thước của ảnh được tải lên là bao nhiêu, API sẽ giảm kích thước ảnh theo tỷ lệ thành 96x96 pixel.
Nếu bạn cần tạo các đường liên kết tương thích từ JavaScript, Thư viện Google Closure sẽ bao gồm các hàm mã hoá và giải mã Base64 được phát hành theo giấy phép Apache.
Truy xuất người dùng với vai trò không phải là quản trị viên
Mặc dù chỉ quản trị viên mới có thể sửa đổi tài khoản người dùng, nhưng mọi người dùng trên miền đều có thể đọc hồ sơ người dùng. Người dùng không phải quản trị viên có thể tạo yêu cầu users.get hoặc users.list với thông số viewType bằng domain_public để truy xuất hồ sơ công khai của người dùng. Phạm vi https://www.googleapis.com/auth/admin.directory.user.readonly là lý tưởng cho trường hợp sử dụng này.
Chế độ xem domain_public cho phép người dùng không phải quản trị viên truy cập vào một nhóm các trường cốt lõi tiêu chuẩn. Đối với trường tuỳ chỉnh, bạn có thể chọn trường đó ở chế độ công khai hay riêng tư khi xác định giản đồ.
Cập nhật ảnh của người dùng
Để cập nhật ảnh của người dùng, 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. userKey có thể là địa chỉ email chính của người dùng, id của người dùng hoặc bất kỳ email nào của bí danh người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
Trong ví dụ này, ảnh của [email protected] được cập nhật:
PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}
Khi cập nhật ảnh, API sẽ bỏ qua height và width.
Phản hồi JSON
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200.
{
"kind": "directory#user#photo",
"id": "the unique user id",
"primaryEmail": "[email protected]",
"mimeType": "the photo mime type",
"height": "the photo height in pixels",
"width": "the photo width in pixels",
"photoData": "web safe base64 encoded photo data"
}
Xoá ảnh của người dùng
Để xoá ảnh của người dùng, 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 Uỷ quyền yêu cầu. userKey có thể là địa chỉ email chính của người dùng, id của người dùng hoặc bất kỳ email nào của bí danh người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
Sau khi bị xoá, ảnh của người dùng sẽ không xuất hiện. Bất cứ khi nào cần ảnh của người dùng, một hình dáng sẽ xuất hiện.
Xoá tài khoản người dùng
Để xoá tài khoản người dùng, hãy sử dụng yêu cầu DELETE sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. userKey có thể là địa chỉ email chính của người dùng, id người dùng duy nhất hoặc một trong các địa chỉ email đại diện của người dùng. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey
Trong ví dụ này, tài khoản người dùng [email protected] sẽ bị xoá:
DELETE https://admin.googleapis.com/admin/directory/v1/users/[email protected]
Phản hồi thành công chỉ trả về mã trạng thái HTTP 200.
Những điều quan trọng cần cân nhắc trước khi xoá người dùng:
- Người dùng đã xoá sẽ không thể đăng nhập được nữa.
- Để biết thêm thông tin về việc xoá tài khoản người dùng, vui lòng tham khảo trung tâm trợ giúp dành cho quản trị viên.
Huỷ xoá tài khoản người dùng
Người dùng đã bị xoá trong 20 ngày qua phải đáp ứng một số điều kiện thì tài khoản của người dùng mới có thể được khôi phục.
Để huỷ xoá tài khoản người dùng, 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. userKey là người dùng riêng biệt id được tìm thấy trong phản hồi của thao tác Truy xuất người dùng đã bị xoá trong vòng 20 ngày qua. Bạn không thể sử dụng địa chỉ email chính của người dùng hoặc một trong các địa chỉ email đại diện của người dùng trong userKey cho thao tác này. Đối với các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete
Trong ví dụ này, người dùng [email protected] sẽ được huỷ xoá. Tất cả tài sản tài khoản trước đây của người dùng này đều được khôi phục:
POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete
Phản hồi thành công chỉ trả về mã trạng thái HTTP 204. Để xem tài khoản của người dùng chưa bị xoá, hãy sử dụng thao tác Truy xuất người dùng.