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.
- Gửi yêu cầu đến API
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 1 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 2 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 4 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 8 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 16 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- 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:
|
| Đổ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 |
|
| 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ề:
|
| 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:
|
| 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. |