Quản lý tài khoản người dùng

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 chỉ định. 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 trong tài khoản Google Workspace của mình. 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 bằng tên miền riêng, 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 thành 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 thông tin uỷ quyền như mô tả trong phần Tìm hiểu về quy trình xác thực và uỷ quyền. Bạn có thể xem các phạm vi hiện có cho Directory API trong danh sách phạm vi OAuth 2.0. Để biết các thuộc tính chuỗi truy vấn của 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ả các yêu cầu tạo đều yêu cầu bạn gửi thông tin cần thiết để hoàn thành yêu cầu. Nếu bạn đang sử dụng thư viện ứng dụng, thì các 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 dữ liệu được định dạng 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. Để xem 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 về API. 

{
"primaryEmail": "liz@example.com",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "liz_im@talk.example.com",
  "primary": true
 }
],
"emails": [
 {
  "address": "liz@example.com",
  "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 HTTP 503 từ máy chủ API cho biết 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.

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 việc chỉ định này.
  • Dịch vụ API sẽ âm thầm bỏ qua việc chỉnh sửa một trường chỉ đọ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ài khoản người dùng được tạo, 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ẽ quyết đị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 di 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.
  • Bạn phải có password cho tài khoản người dùng mới. Nếu bạn chỉ định hashFunction, 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 thuần tuý 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 về API.
  • Đối với người dùng sử dụng gói linh hoạt cho Google Workspace, việc tạo người dùng bằng API này sẽ ảnh hưởng đến chi phí và 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 Thông tin thanh toán API.
  • 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 có 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 khác của tài khoản. Để biết thêm thông tin về người dùng thuộc nhiều miền, hãy xem thông tin về API cho nhiều miền.
  • Có thể có cá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 ở định dạng tên_người_dùng_của_khách@tên_miền_của_bạn.com. 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, thì tài khoản đó sẽ được chuyển đổi thành một tài khoản Google Workspace đầy đủ. Tài khoản sẽ giữ nguyên các quyền hiện tại đối với tệp trên Drive. Xem phần 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 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 duy nhất 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.

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 phiên bản của User. Tuy nhiên, Directory API hỗ trợ ngữ nghĩa 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ỉ có địa chỉ email công việc được cung cấp.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    }
  ]
}

Yêu cầu bên dưới sẽ cập nhật givenName từ "Elizabeth" thành "Liz", đồng thời thêm một địa chỉ email nhà riêng. 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/liz@example.com

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    },
    {
      "address": "liz@home.com",
      "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 để có hiệu lực 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 biệt hiệu để đảm bảo việc gửi thư diễn ra 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.
  • Nói 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 liên tục vì địa chỉ email có thể thay đổi.
  • Để xem danh sách đầy đủ các ảnh hưởng của việc đổi tên người dùng trên các ứng dụng 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 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 duy nhất 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. Để biết 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 về 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à liz@example.com đã trở thành quản trị viên cấp cao: 

POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/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ệ với người dùng

Directory API sử dụng trường relations để xác định các loại mối quan hệ 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ư mối quan hệ với 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ệ sẽ xuất hiện trong thẻ "Người có liên quan" của người dùng trong mọi ứng dụng Google Workspace hỗ trợ thẻ này. Để xem ví dụ về nơi thẻ này xuất hiện, hãy xem bài viết Thêm thông tin vào hồ sơ người dùng trong Danh bạ.

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ệ giữa người quản lý và 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ọ bằng loại manager. Để biết các loại được phép, hãy xem tài liệu tham khảo về đố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 một nội dung yêu cầu JSON có chứa 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ể đề cập đến từng người trong danh sách để thay đổi loại mối quan hệ hoặc xoá họ. 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 làm 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 như 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 mộ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 như 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 duy nhất 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. Để biết 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 thay thế là liz@example.com: 

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

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": "liz@example.com",
 "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": "lizim@talk.example.com",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "liz@example.com",
   "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": [
  "lizsmith@example.com",
  "lsmith@example.com"
 ],
 "nonEditableAliases": [
  "liz@test.com"
 ],
 "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 như 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/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*

Để biết 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 đều đượ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 người dùng tiếp theo trong phản hồi này. Theo mặc định, hệ thống sẽ trả về danh sách gồm 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": "liz@example.com",
   "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": "lizim@talk.example.com",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "liz@example.com",
     "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": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "admin2@example.com",
   "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": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "second_admin@example.com"
   ],
   "nonEditableAliases": [
    "admin@test.com"
   ],
   "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 như 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/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 customer là giá trị my_customer hoặc customerId.
  • Sử dụng chuỗi my_customer để biểu thị customerId của tài khoản.
  • Là quản trị viên đại lý, hãy sử dụng customerId của khách hàng được bán lại. Đối với 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.
  • Chuỗi truy vấn orderBy (không bắt buộc) xác định xem danh sách có đượ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ụng orderBy, bạn cũng có thể dùng chuỗi truy vấn sortOrder để liệt kê kết quả theo thứ tự tăng dần hoặc giảm dần.
  • Chuỗi truy vấn query khô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ả các trường chính và trường tuỳ chỉnh. Hãy xem phần Tìm kiếm người dùng để biết ví dụ.

Để biết 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, một quản trị viên tài khoản đang yêu cầu trả về tất cả người dùng trong tài khoản với một mục nhập người dùng trên mỗi trang phản hồi. nextPageToken sẽ 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": "admin2@example.com",
   "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": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "second_admin@example.com"
   ],
   "nonEditableAliases": [
     "another_admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "liz@example.com",
   "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": "liz@example.com",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "test3@example.com",
   "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": "test@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "tester3@example.com"
   ],
   "nonEditableAliases": [
    "third@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "work_admin@example.com",
   "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": "work_admin@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "my_alias@example.com"
   ],
   "nonEditableAliases": [
    "other_alias@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

Truy xuất người dùng bị xoá gần đây

Để truy xuất tất cả người dùng đã bị xoá trong khoảng thời gian 20 ngày gần nhất của một tài khoản hoặc của 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 đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu. Để huỷ xoá người dùng, hãy xem phần 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 phụ 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. Để biết 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. Và để dễ đọc, ví dụ này sử dụng dấu xuống dòng: 

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=true
 Nếu một tài khoản có nhiều miền, bạn có thể truy xuất những 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. Để dễ đọc, ví dụ này sử dụng dấu xuống dòng: 
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 customer là giá trị my_customer hoặc customerId.
  • 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.
  • Là quản trị viên đại lý, hãy sử dụng customerId của khách hàng được bán lại. Đối với 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.

Để biết 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, một quản trị viên tài khoản đang yêu cầu tất cả người dùng đã bị 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": "user1@example.com"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user3@example.com"
  }
 ],
 "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, là ảnh hồ sơ mới nhất trên Google. Để truy xuất bức ả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. Để biết 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, ảnh mới nhất của liz@example.com sẽ được trả về:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/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": "liz@example.com",
 "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 của bạn tương tự như "base64url" trong RFC 4648. Điều này có nghĩa là:

  • Ký tự dấu 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 ngang (-).
  • Ký tự dấu bằng (=) được thay thế bằng dấu hoa thị (*).
  • Đối với khoảng đệm, ký tự dấu chấm (.) được dùng thay vì định nghĩa baseURL RFC-4648 sử dụng dấu bằng (=) cho khoảng đệm. Việc này được thực hiện để đơn giản hoá quá trình phân tích cú pháp URL.
  • Dù kích thước của ảnh được tải lên là bao nhiêu, API này cũng sẽ giảm kích thước ảnh theo tỷ lệ xuống 96x96 pixel.

Nếu 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 tư cách là người dùng không phải 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 là quản trị viên có thể đưa ra yêu cầu users.get hoặc users.list với tham 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ựa chọn 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 xem trường đó nên ở 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 như 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 trong số các email đại diện của người dùng. Để biết 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 liz@example.com được cập nhật: 

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/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": "liz@example.com",
 "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 thông tin uỷ quyền như 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 trong số các email đại diện của người dùng. Để biết 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, hệ thống sẽ hiển thị hình bóng thay thế.

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 như 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 duy nhất 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. Để biết 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 liz@example.com sẽ bị xoá: 

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

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 bị xoá sẽ không đă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 quản trị.

Khôi phục tài khoản người dùng

Người dùng bị xoá trong vòng 20 ngày qua phải đáp ứng một số điều kiện thì mới có thể khôi phục tài khoản của người dùng đó.

Để khôi phục 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 như mô tả trong phần Uỷ quyền yêu cầu. userKey là người dùng riêng biệt id có 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 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. Để biết 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 liz@example.com sẽ được khôi phục. Tất cả các tài sản trước đây của người dùng này trong tài khoản đề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.