Directory API: Giới hạn và hạn mức

Các giới hạn và hạn mức bảo vệ cơ sở hạ tầng của Google khỏi quy trình tự động sử dụng Directory API theo cách không phù hợp. Việc đưa ra quá nhiều yêu cầu từ API có thể dẫn đến lỗi chính tả vô hại hoặc có thể là do một hệ thống được thiết kế không hiệu quả khiến bạn thực hiện các lệnh gọi API không cần thiết. Bất kể nguyên nhân là gì, bạn đều cần chặn lưu lượng truy cập từ một nguồn cụ thể khi nó đạt đến một mức nhất định để đảm bảo tình trạng chung của hệ thống Google Workspace. Quy trình này đảm bảo rằng hành động của một nhà phát triển không được ảnh hưởng tiêu cực đến cộng đồng lớn hơn.

Trong trường hợp hiếm gặp là yêu cầu API không thành công, API sẽ trả về mã trạng thái HTTP và lý do gây ra lỗi. Ngoài ra, phần nội dung của phản hồi còn chứa thông tin mô tả chi tiết về nguyên nhân gây ra lỗi.

Danh sách sau đây cho thấy mã lỗi có thể xảy ra, nguyên nhân, nội dung mô tả tương ứng và hành động được đề xuất cho các lỗi do đạt đến hạn mức.

Mã Lý do Nội dung mô tả Việc nên làm
403 userRateLimitExceeded Cho biết rằng đã vượt quá giới hạn số lượng yêu cầu người dùng. Giá trị mặc định được đặt trong bảng điều khiển Google Cloud là 2.400 truy vấn/phút/người dùng đối với mỗi dự án trên Google Cloud. Tăng giới hạn trên mỗi người dùng trên trang Hạn mức API SDK dành cho quản trị viên của dự án Google Cloud hoặc giảm tốc độ gửi yêu cầu bằng phương thức thời gian đợi luỹ thừa.
403 quotaExceeded Cho biết rằng đã đạt đến giới hạn số lượng yêu cầu đồng thời cho một thao tác nhất định. Thử sử dụng lại phương pháp thời gian đợi luỹ thừa. Bạn cần giảm tốc độ gửi yêu cầu.
429 rateLimitExceeded Cho biết rằng đã đạt đến giới hạn số lượng yêu cầu đồng thời cho một thao tác nhất định. Thử lại bằng cách sử dụng tính năng thời gian đợi luỹ thừa. Bạn phải giảm tốc độ gửi các yêu cầu. Giới hạn này áp dụng cho mỗi tài khoản Google Workspace, chứ không phải theo ứng dụng API hoặc mỗi người dùng. Bạn không thể tăng hạn mức này.

Triển khai thuật toán thời gian đợi luỹ thừa

Thời gian đợi luỹ thừa là quá trình máy khách định kỳ thử lại một yêu cầu không thành công trong một khoảng thời gian tăng dần. Đây là một chiến lược xử lý lỗi tiêu chuẩn cho các ứng dụng mạng. Việc sử dụng thuật toán thời gian đợi luỹ thừa giúp tăng hiệu quả sử dụng băng thông, giảm số lượng yêu cầu cần thiết để có được phản hồi thành công và tối đa hoá thông lượng yêu cầu trong các môi trường đồng thời.

Quy trình triển khai thuật toán thời gian đợi luỹ thừa đơn giản như sau.

  1. Gửi yêu cầu đến API
  2. Nhận phản hồi lỗi có mã lỗi có thể thử lại
  3. Đợi 1 giây + random_number_milliseconds giây
  4. Thử gửi lại yêu cầu
  5. Nhận phản hồi lỗi có mã lỗi có thể thử lại
  6. Đợi 2 giây + random_number_milliseconds giây
  7. Thử gửi lại yêu cầu
  8. Nhận phản hồi lỗi có mã lỗi có thể thử lại
  9. Đợi 4 giây + random_number_milliseconds giây
  10. Thử gửi lại yêu cầu
  11. Nhận phản hồi lỗi có mã lỗi có thể thử lại
  12. Đợi 8 giây + random_number_milliseconds giây
  13. Thử gửi lại yêu cầu
  14. Nhận phản hồi lỗi có mã lỗi có thể thử lại
  15. Chờ 16 giây + random_number_milliseconds giây
  16. Thử gửi lại yêu cầu
  17. Nếu bạn vẫn gặp lỗi, hãy dừng lại và ghi lại lỗi đó.

Trong quy trình trên, random_number_milliseconds là một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1000. Việc này là cần thiết để tránh một số lỗi khoá nhất định trong một số quá trình triển khai đồng thời. random_number_milliseconds phải được xác định lại sau mỗi lần chờ.

Lưu ý: thời gian chờ luôn là (2 ^ n) + random_number_milliseconds, trong đó n là một số nguyên tăng đơn điệu được xác định ban đầu là 0. n được tăng thêm 1 cho mỗi lần lặp (mỗi yêu cầu).

Thuật toán sẽ được đặt để kết thúc khi n là 5. Mức trần này chỉ được áp dụng để ngăn ứng dụng thử lại vô hạn, dẫn đến độ trễ tổng cộng khoảng 32 giây trước khi một yêu cầu bị coi là "lỗi không thể khôi phục". Ứng dụng API của bạn có thể triển khai nhiều lần thử hơn nếu cần.

Hạn mức và giới hạn API

Danh mục giới hạn API Giới hạn
Tạo người dùng Bạn không thể tạo nhiều hơn 10 người dùng trên mỗi miền mỗi giây bằng API thư mục.
Nhóm đã được thêm làm thành viên vào một nhóm khác Có thể phải mất tới 10 phút thì các thành viên của nhóm con mới xuất hiện với tư cách là thành viên của nhóm mẹ. Giới hạn này có thể thay đổi tuỳ thuộc vào dung lượng của hệ thống.
Thiết bị di động

Sử dụng API Thư mục, bạn có thể thực hiện tối đa:

  • 20 yêu cầu hành động mỗi giây.
  • 20 yêu cầu xoá mỗi giây.
  • 10 yêu cầu mỗi giây.
  • 10 yêu cầu danh sách mỗi giây.
Đổi tê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ụ. 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. Để biết thêm chi tiết, hãy xem phần Cập nhật người dùng.
Tạo/cập nhật đơn vị tổ chức
  • Bạn không thể tạo/cập nhật nhiều hơn 1 đơn vị tổ chức cho mỗi khách hàng mỗi giây bằng API Directory.
  • Hệ thống phân cấp đơn vị tổ chức của khách hàng chỉ có tối đa 35 cấp độ chuyên sâu.
  • Tổng số đơn vị tổ chức cho mỗi khách hàng không được vượt quá 40.000.
Danh mục hạn mức API Hạn mức
Thiết bị Chrome annotatedLocation, tối đa ký tự Số lượng ký tự tối đa cho thông tin vị trí của thiết bị là 200.
Thiết bị Chrome notes, tối đa ký tự Số lượng ký tự tối đa cho thông tin ghi chú của thiết bị là 500.
Thiết bị Chrome, tối đa user ký tự Số lượng ký tự tối đa cho tên người dùng thiết bị là 100.
Bí danh miền, tối đa Số bí danh miền tối đa là 20.
Nhóm, nội dung mô tả Số ký tự tối đa trong một nội dung mô tả là 4.096.
Số nhóm, cho mỗi tài khoản Đối với tài khoản G Suite phiên bản cũ, không tính phí, số lượng nhóm giới hạn ở 10. Các phiên bản khác không có giới hạn về số lượng nhóm.
Số nhóm, số thành viên mỗi nhóm Khi sử dụng tài khoản G Suite phiên bản cũ miễn phí, một nhóm có thể có tối đa 100 thành viên. Các phiên bản khác không có giới hạn về số lượng thành viên mà một nhóm có thể có. Để biết giới hạn về số thành viên trong nhóm cho mỗi người dùng, hãy xem bài viết Tìm hiểu các chính sách và giới hạn của Groups
Chuỗi truy vấn maxResults API này trả về:
  • Chrome và thiết bị di động – Chế độ mặc định và tối đa 100 mục trên mỗi trang.
  • Nhóm và thành viên nhóm – Mặc định và tối đa 200 mục nhập trên mỗi trang.
  • Người dùng – Theo mặc định, có 100 mục nhập và tối đa 500 mục nhập trên mỗi trang.
Tài nguyên đại diện của người dùng và tài nguyên của đơn vị tổ chức không sử dụng tính năng phân trang phản hồi. Tất cả email chính của người dùng đều được trả về theo thứ tự bảng chữ cái và thứ tự phản hồi không phân biệt chữ hoa chữ thường.
Nhiều miền, số lượng miền tối đa được phép trong một tài khoản 600 (1 miền chính + 599 miền bổ sung)
Đơn vị tổ chức, số người dùng tối đa được di chuyển cùng một lúc Bạn có thể di chuyển 20 người dùng cùng một lúc. Đồng thời, địa chỉ email chính của người dùng phải tồn tại trong tài khoản.
Bí danh của người dùng Tổng số biệt hiệu được phép sử dụng cho mỗi tài khoản người dùng là 30.
Bí danh người dùng, sử dụng bí danh đã xóa Bạn có thể sử dụng lại email đại diện đã bị xoá của người dùng ngay lập tức.

Các loại giới hạn khác Giới hạn và nguyên tắc
Thanh toán và tạo người dùng Đố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í. Ví dụ: Nếu bạn đang sử dụng gói linh hoạt cho Google Workspace, thì việc tạo 10 người dùng sẽ khiến 10 giấy phép Google Workspace được đăng lên tài khoản của bạn sẽ bị tính phí, theo tỷ lệ thời gian tạo. Nếu đang sử dụng gói hằng năm, tức là bạn đã cam kết thanh toán trước cho một số lượng giấy phép nhất định và bạn chỉ có thể tạo số lượng người dùng theo cam kết của mình. Để biết thêm thông tin về các gói thanh toán và tài khoản thanh toán của bạn, hãy xem trung tâm trợ giúp dành cho quản trị viên.
Họ và tên Họ và tên có tối đa 40 ký tự. Các ký tự này hỗ trợ ký tự Unicode/UTF-8 và có thể chứa dấu cách, chữ cái (a-z), số (0-9), dấu gạch ngang (-), dấu gạch chéo lên (/) và dấu chấm (.). Để biết thêm thông tin về quy tắc sử dụng ký tự, hãy xem trung tâm trợ giúp quản trị.
Nhóm, đang xoá Việc xóa một nhóm sẽ không xóa tài khoản người dùng của thành viên trong nhóm đó.
Nhóm và thành viên nhóm, thay đổi địa chỉ email Trong phiên bản API này, bạn có thể thay đổi địa chỉ email của nhóm trước khi bật dịch vụ Google Workspace. Sử dụng Bảng điều khiển dành cho quản trị viên để thay đổi địa chỉ email của thành viên trong nhóm. Sau khi được thay đổi, API sẽ tự động phản ánh các thay đổi đối với địa chỉ email.
Nhóm, chế độ cài đặt Các chế độ cài đặt quyền truy cập vào nhóm, lựa chọn chia sẻ, tính năng giám sát và bản lưu trữ nội dung thảo luận được quản lý bằng Bảng điều khiển dành cho quản trị viên. Để biết thêm thông tin về các chế độ cài đặt nhóm, hãy truy cập vào trung tâm trợ giúp quản trị.
Nhóm, gửi tin nhắn Để ngăn chặn thư rác và hành vi sử dụng email sai mục đích, Google giới hạn số lượng thư bạn có thể gửi cùng một lúc cho người nhận bên ngoài. Nếu bạn gửi thư cho một nhóm, mỗi thành viên bên ngoài sẽ được tính là một người nhận. Để biết thêm thông tin, hãy xem bài viết Giới hạn gửi email và Ngăn chặn việc thư gửi đến người dùng Gmail bị chặn hoặc chuyển vào thư mục thư rác .
Nhóm, đang gửi thông báo NDR Bạn không thể gửi hoặc chuyển tiếp biên nhận không gửi đi (NDR), còn gọi là "thư trả lại" cho một nhóm.
Nhóm do người dùng tạo, giới hạn Để biết các giới hạn về nhóm do người dùng tạo, hãy xem trung tâm trợ giúp quản trị
Đơn vị tổ chức, bật/tắt dịch vụ Sử dụng Bảng điều khiển dành cho quản trị viên để quản lý việc bật và tắt dịch vụ cho một đơn vị tổ chức.
Mật khẩu Có thể chứa bất kỳ tổ hợp ký tự nào. Cần có tối thiểu 8 ký tự. Độ dài tối đa là 100 ký tự.
Photos Trong phiên bản API này, ảnh là ảnh hồ sơ mới nhất trên Google của người dùng.
Tên người dùng Tên người dùng có thể chứa các chữ cái (a-z), số (0-9), dấu gạch ngang (-), dấu gạch dưới (_) và Google Workspace nhận dạng dấu chấm hoặc dấu chấm (.). Điều này không giống với Gmail. Tên người dùng không được chứa dấu bằng (=), dấu ngoặc vuông (<,>) hoặc nhiều dấu chấm (.) trong một hàng. Để biết thêm thông tin, hãy xem trung tâm trợ giúp quản trị.
Tên người dùng, đổi tên Google Hangouts sẽ hủy tất cả các lời mời trò chuyện đã nhớ sau khi đổi tên. Người dùng phải yêu cầu lại quyền để trò chuyện với bạn bè. Trong trường hợp thiết lập chế độ chuyển tiếp email, tên người dùng cũ sẽ được giữ lại làm email đại diện để đả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à tên này sẽ không được cung cấp dưới dạng tên người dùng mới. Để biết các thông tin chi tiết quan trọng về tác động của việc đổi tên người dùng, hãy xem trung tâm trợ giúp quản trị. Sử dụng thao tác Xóa email đại diện của người dùng để xóa email đại diện sau khi đổi tên.
Người dùng trong nhiều miền 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. Có nhiều thành phần của miền:
  • Miền chính – Miền chính của tài khoản là miền của quản trị viên đã chấp nhận thoả thuận về Điều khoản dịch vụ của Google Workspace. Miền này ở cấp tài khoản trong đơn vị tổ chức cấp cao nhất. Khi đăng ký tài khoản Google Workspace, bạn nên sử dụng miền doanh nghiệp của mình cho miền chính, đồng thời dành riêng các miền khác cho các mục đích sử dụng chuyên biệt như thí điểm và thử nghiệm.
    • Tất cả quản trị viên cấp cao đều có thể quản lý toàn bộ tài khoản.
    • API này không thể thay đổi hoặc di chuyển miền chính của tài khoản Google Workspace. Tuy nhiên, API có thể đổi tên tài khoản của người dùng, thay đổi địa chỉ email của tài khoản từ miền này sang miền khác.
    • Đối với tài khoản Google Workspace, bạn có 21 ngày để xác minh quyền sở hữu miền chính của mình. Đối với các miền khác, bạn phải xác minh quyền sở hữu miền trước khi sử dụng miền cho địa chỉ email chính của người dùng. Trong những trường hợp này, thời gian gia hạn 21 ngày không áp dụng.
    • Trong phiên bản API này, các chế độ cài đặt của miền chính sẽ áp dụng cho tất cả các miền liên kết với tài khoản, ngoại trừ quyền truy cập của người dùng vào các dịch vụ của Google Workspace.
  • Miền của tài khoản bổ sung -- Sau khi thiết lập miền chính và thiết lập tài khoản của mình, bạn có thể thêm các miền bổ sung vào tài khoản. Đối với các miền khác, hãy xác minh quyền sở hữu khi thiết lập miền này và trước khi sử dụng miền cho địa chỉ email chính của người dùng.
  • Miền gia đình của người dùng -- Miền sử dụng trong địa chỉ email chính của người dùng là miền gia đình của người dùng. Miền này có thể là bất kỳ miền nào trong tài khoản, bao gồm cả miền chính.
Để biết các giới hạn mới nhất đối với nhiều miền, hãy xem nhiều giới hạn cho nhiều miền. Thông tin này bao gồm thông tin về bí danh miền, hợp nhất tài khoản, v.v.
Cảnh báo, thành viên nhóm GROUP_CANNOT_LAST_CYCLE – API không cho phép có chu kỳ trong tư cách thành viên nhóm. Ví dụ: Nếu nhóm 1 là thành viên của nhóm 2 thì nhóm 2 không thể là thành viên của nhóm 1.