Trang này được dịch bởi Cloud Translation API.

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

API Thư mục 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 bằng tên miền riêng của mình, thì bạn không thể tạo tài khoản người dùng mới cho đến khi bạn 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 Các 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 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ó của API Thư mục trong danh sách phạm vi của 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": "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 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.

Những điều cần lưu ý về tài khoản mới là:

Nếu Tài khoản Google đã mua giấy phép 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 thành 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 một 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 đó thuộc đơn vị tổ chức cấp cao nhất. Đơn vị tổ chức của người dùng xác định những dịch vụ của Google Workspace mà người dùng đó có quyền sử dụng. 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ơ cấu tổ chức, hãy xem trung tâm trợ giúp quản trị. Để biết thêm thông tin về việc di chuyển người dùng sang một tổ chức khác, hãy xem phần Cập nhật người dùng.
Cần 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 bạn không chỉ định mật khẩu thì phải ở dạng văn bản rõ ràng và dài 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ẽ có ảnh hưởng về mặt tiền bạc và tài khoản thanh toán của khách hàng của bạn sẽ bị tính phí. Để 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 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 trong nhiều miền, hãy xem phần Thông tin về API nhiều miền.
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 đó. Xem phần Tìm và giải quyết 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 (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 visit's_username@your_domain.com. Nếu bạn thêm một người dùng có cùng tên người dùng làm 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 đó sẽ vẫn có 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 và bao gồm quyền được mô tả trong bài viết Uỷ quyền yêu cầu. userKey có thể là địa chỉ email chính của người dùng, người dùng riêng biệt id hoặc một trong những đị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à phản hồi đều chứa một thực thể của User. Tuy nhiên, API Thư mục 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ỉ 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 đị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 sử 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 và dịch vụ của trình duyệt.
Quá trình đổi tên tài khoản người dùng có thể mất tối đa 10 phút để có hiệu lực trên tất cả các dịch vụ.
Khi bạn đổi tên một người dùng, tên người dùng cũ sẽ được giữ lại dưới dạng bí danh để đảm bảo việc gửi thư liên tục trong trường hợp bạn thiết lập chế độ chuyển tiếp email và sẽ không dùng được dưới dạng tên người dùng mới.
Nhìn chung, bạn cũng không nên dùng địa chỉ email của người dùng làm khoá cho dữ liệu ổn định, vì địa chỉ email có thể thay đổi.
Để xem danh sách đầy đủ tác độ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 tham khảo 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 và thêm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. userKey có thể là địa chỉ email chính của người dùng, người dùng riêng biệt id hoặc một trong những đị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 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

API Thư mục 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 bối cảnh kinh doanh, mọi người thường sử dụng trường này cho các mối quan hệ giữa người quản lý và nhân viên và trợ lý, nhưng trường này cũng hỗ trợ nhiều loại khác. Mối quan hệ này sẽ xuất hiện trong thẻ "Người có liên quan" của người dùng trong bất kỳ ứng dụng nào của Google Workspace có 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ơ Thư mục của người dùng.

Tạo mối quan hệ giữa những 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ọ bằng loại manager. Để biết các loại được cho 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 đang sở hữu với 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ể xử lý từng người được liệt kê để thay đổi loại mối quan hệ hoặc xoá họ. Trong ví dụ trên, để xóa mối quan hệ người quản lý hiện có và đặt trình quản lý đường chấm làm trình 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 đang sở hữu với tất cả các giá trị của trường như bạn muốn.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

Để xóa tất cả cá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 và bao gồm quyền uỷ quyền được mô tả trong phần Cho phép yêu cầu. userKey có thể là địa chỉ email chính của người dùng, người dùng riêng biệt id hoặc một trong những đị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ụ sau 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 email đại diện 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 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 và bao gồm quyền 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 phương thức trả về 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 được trả về với tối đa 2 miền người dùng cho mỗi trang phản hồi. Có một nextPageToken cho danh sách người dùng theo dõi 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 trong đị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):

Lưu ý: Khi truy xuất tất cả người dùng trong một miền, giá trị lastLoginTime có thể không chính xác. Để nhận được giá trị chính xác nhất cho lastLoginTime, hãy truy xuất người dùng.

{
 "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 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/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 của đạ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 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 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ả trường cốt lõi 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, 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 bằng 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 của đại lý yêu cầu tất cả người dùng trong tài khoản được bán lại. Tài khoản này 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:

Lưu ý: Khi truy xuất tất cả người dùng tài khoản, giá trị của lastLoginTime có thể không chính xác. Để nhận được giá trị chính xác nhất cho lastLoginTime, hãy truy xuất người dùng.

{
 "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 vòng 20 ngày qua từ một tài khoản hoặc từ 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 quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. Để hủy xóa người dùng, hãy xem Hủy xóa người dùng.

Để truy xuất những người dùng đã bị xoá trong vòng 20 ngày qua từ 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 phản hồi và yêu cầu 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 phương thức trả về 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

Lưu ý: Với chế độ cài đặt showDeleted=false, yêu cầu sẽ trả về cùng một phản hồi tương tự như Truy xuất tất cả người dùng trong một miền.

Nếu 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 khoảng thời gian 20 ngày qua từ toàn bộ tài khoản, hãy sử dụng yêu cầu GET sau. Để 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/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 để thể hiện customerId của tài khoản.
Là quản trị viên của đạ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 miền. Phản hồi thu đượ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.

Lưu ý: Với chế độ cài đặt showDeleted=false, yêu cầu sẽ trả về cùng một phản hồi dưới dạng Truy xuất tất cả người dùng tài khoản. Đối với các thuộc tính phản hồi và yêu cầu của người dùng, 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 tất cả người dùng đã bị xóa 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 truy xuất một hình thu nhỏ của ảnh, ả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 và bao gồm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. userKey có thể là địa chỉ email chính của người dùng, id 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 trên web của API cho ảnh của bạn tương tự như "base64url" 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 nối (-).
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 cho định nghĩa baseURL RFC-4648, vốn sử dụng dấu bằng (=) cho khoảng đệm. Việc này nhằm đơ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, API sẽ giảm kích thước ảnh theo tỷ lệ xuống 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 đóng của Google sẽ bao gồm các chức năng 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 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ể đưa ra yêu cầu users.get hoặc users.list với tham số viewType bằng với 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 một trường tuỳ chỉnh, bạn có thể chọn xem 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 và bao gồm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. userKey có thể là địa chỉ email chính của người dùng, người dùng id 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.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Trong ví dụ này, ảnh 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 một ảnh, height và width sẽ bị API bỏ qua.

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 và bao gồm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. userKey có thể là địa chỉ email chính của người dùng, người dùng id 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.

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Sau khi bị xóa, ảnh của người dùng sẽ không hiển thị. Bất cứ khi nào cần có ảnh của người dùng thì thay vào đó, một hình 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 và thêm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. userKey có thể là địa chỉ email chính của người dùng, người dùng riêng biệt id hoặc một trong những đị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 lưu ý 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 xóa 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ị xóa trong vòng 20 ngày qua phải đáp ứng một số điều kiện nhất định thì tài khoản của người dùng đó mới có thể được khôi phục.

Để huỷ xoá một tài khoản người dùng, 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 Yêu cầu uỷ quyền. 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 đã xoá trong vòng 20 ngày qua. Địa chỉ email chính hoặc một trong các địa chỉ email đại diện của người dùng không được sử 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, không được xóa. Tất cả thuộc tính tài khoản trước đó của người dùng này đượ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 bị huỷ xoá, hãy sử dụng thao tác Truy xuất người dùng.