Hạn mức và giới hạn giúp bảo vệ cơ sở hạ tầng của Google khỏi một quy trình tự động sử dụng Directory API theo cách không phù hợp. Việc gửi quá nhiều yêu cầu từ một API có thể là do lỗi chính tả không gây hại hoặc có thể là do hệ thống được thiết kế không hiệu quả, dẫn đến các lệnh gọi API không cần thiết. Bất kể nguyên nhân là gì, việc chặn lưu lượng truy cập từ một nguồn cụ thể khi lưu lượng truy cập đó đạt đến một mức nhất định là cần thiết để đảm bảo hệ thống Google Workspace hoạt động ổn định. Việc này đảm bảo rằng hành động của một nhà phát triển không thể ả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 của bạn 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 có nội dung mô tả chi tiết về nguyên nhân gây ra lỗi.
Danh sách sau đây cho biết các mã lỗi, lý do, nội dung mô tả tương ứng và hành động nên thực hiện đối với các lỗi do vượt quá hạn mức.
| Mã | Lý do | Mô tả | Việc nên làm |
|---|---|---|---|
| 403 | userRateLimitExceeded | Cho biết rằng bạn đã vượt quá giới hạn tốc độ người dùng. Giá trị mặc định được đặt trong Google Cloud Console là 2.400 truy vấn mỗi phút cho mỗi người dùng cho mỗi dự án trên Google Cloud. | Tăng giới hạn cho mỗi người dùng trên trang Hạn mức API Admin SDK của dự án Google Cloud, hoặc giảm tốc độ gửi yêu cầu bằng cách sử dụng thuật toán thời gian chờ luỹ tiến. |
| 403 | quotaExceeded | Cho biết rằng bạn đã đạt đến giới hạn số 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 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 bạn đã đạt đến giới hạn số 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 thuật toán thời gian đợi luỹ thừa. Bạn phải giảm tốc độ gửi 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 cho mỗi ứ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
Thuật toán thời gian đợi luỹ thừa là quy trình mà ứng dụng định kỳ thử lại một yêu cầu không thành công trong 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, đồng thời 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.
- Đưa ra yêu cầu đối với API
- Nhận được một phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 1 giây +
random_number_millisecondsgiây - Yêu cầu thử lại
- Nhận được một phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 2 giây +
random_number_millisecondsgiây - Yêu cầu thử lại
- Nhận được một phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 4 giây +
random_number_millisecondsgiây - Yêu cầu thử lại
- Nhận được một phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 8 giây +
random_number_millisecondsgiây - Yêu cầu thử lại
- Nhận được một phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 16 giây +
random_number_millisecondsgiây - Yêu cầu thử lại
- Nếu bạn vẫn gặp lỗi, hãy dừng và ghi lại lỗi.
Trong luồng trên, random_number_milliseconds là một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1000. Điều này là cần thiết để tránh một số lỗi khoá trong một số cách 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 dần ban đầu được xác định 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 việc tổng độ trễ khoảng 32 giây trước khi một yêu cầu được coi là "lỗi không thể khôi phục". Nếu cần, ứng dụng API của bạn có thể triển khai số lần thử cao hơn.
Hạn mức và hạn ngạch 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 quá 10 người dùng cho mỗi miền mỗi giây bằng Directory API. |
| Nhóm được thêm làm thành viên của một nhóm khác | Có thể mất đến 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 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. |
| Các thiết bị di động |
Khi sử dụng Directory API, bạn có thể thực hiện tối đa:
|
| Đổi tên người dùng | Có thể mất đến 10 phút để áp dụng cho 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 trình duyệt và dịch vụ. Để 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ự
|
Tên người dùng thiết bị có tối đa 100 ký tự. |
| Số lượng bí danh miền tối đa | Số lượng bí danh miền tối đa là 20. |
| Nhóm, nội dung mô tả | Số lượng ký tự tối đa trong nội dung mô tả là 4.096. |
| Số nhóm cho mỗi tài khoản | Với tài khoản G Suite Legacy Free Edition, số lượng nhóm bị giới hạn ở mức 10. Các phiên bản khác không giới hạn số lượng nhóm. |
| Nhóm, số thành viên trên mỗi nhóm | Với tài khoản G Suite Legacy Free Edition, một nhóm có thể chứa tối đa 100 thành viên. Các phiên bản khác không giới hạn số lượng thành viên mà một nhóm có thể có. Để biết hạn mức 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à hạn mức 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ố lượng 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. Địa chỉ email chính của người dùng phải đã tồn tại trong tài khoản. |
| Bí danh người dùng | Tổng số bí danh được phép cho mỗi tài khoản người dùng là 30. |
| Email đại diện của người dùng, sử dụng email đại diện đã bị xoá | Bạn có thể sử dụng lại ngay lập tức một bí danh người dùng đã bị xoá. |
| Các loại hạn mức 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 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. 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 tài khoản của bạn bị tính phí cho 10 giấy phép Google Workspace, được tính theo tỷ lệ từ thời điểm tạo. Nếu đang dùng gói hằng năm, bạn đã cam kết trả trước cho một số lượng giấy phép nhất định và 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 tên này hỗ trợ ký tự Unicode/UTF-8 và có thể chứa dấu cách, chữ cái (a-z), chữ số (0-9), dấu gạch ngang (-), dấu gạch chéo (/) và dấu chấm (.). Để biết thêm thông tin về các quy tắc sử dụng ký tự, hãy xem trung tâm trợ giúp về hoạt động quản trị. |
| Xoá nhóm | Việc xoá một nhóm sẽ không xoá tài khoản người dùng của thành viên 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 một 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 của Google để thay đổi địa chỉ email của một thành viên trong nhóm. Sau khi bạn thay đổi, API sẽ tự động phản ánh những thay đổi về địa chỉ email. |
| Groups, chế độ cài đặt | Các chế độ cài đặt quyền truy cập của nhóm, lựa chọn chia sẻ, hoạt động giám sát và kho lưu trữ cuộc thảo luận được quản lý bằng Bảng điều khiển dành cho quản trị viên của Google. Để biết thêm thông tin về chế độ cài đặt nhóm, hãy xem trung tâm trợ giúp dành cho quản trị viên. |
| Nhóm, gửi tin nhắn | Để ngăn chặn thư rác và hành vi sai trái qua email, Google giới hạn số lượng thư bạn có thể gửi cùng lúc cho người nhận bên ngoài. Nếu bạn gửi thư cho một nhóm, thì 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 Hạn mức gửi email và Ngăn tình trạng 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, 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 được (NDR), còn gọi là "thư bị trả lại", cho một nhóm. |
| Các nhóm do người dùng tạo, hạn chế | Để biết hạn mức 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 của Google để 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 mọi tổ hợp ký tự. Bạn phải nhập ít nhất 8 ký tự. Độ dài tối đa là 100 ký tự. |
| Ảnh | Trong phiên bản API này, ảnh là ảnh hồ sơ mới nhất của người dùng trên Google. |
| Tên người dùng | Tên người dùng có thể chứa các chữ cái (a-z), chữ 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 (.). Đ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 (<,>) hoặc nhiều dấu chấm (.) liên tiếp. Để biết thêm thông tin, hãy xem trung tâm trợ giúp về hoạt động quản trị. |
| Tên người dùng, đổi tên | Google Hangouts sẽ loại bỏ tất cả lời mời trò chuyện đã ghi nhớ sau khi bạn đổi tên. Người dùng phải yêu cầu cấp lại quyền trò chuyện với bạn bè. Tên người dùng cũ sẽ được giữ lại dưới dạng email đại diện để đả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à sẽ không được dùng làm tên người dùng mới. Để biết thông tin 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 Xoá email đại diện của người dùng để xoá email đại diện sau khi đổi tên. |
| Người dùng thuộc 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 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. Nhiều thành phần miền là:
|
| Cảnh báo, thành viên trong nhóm | GROUP_CANNOT_CONTAIN_CYCLE – API không cho phép có vòng lặp trong thành viên nhóm. Ví dụ: nếu group1 là thành viên của group2, thì group2 không thể là thành viên của group1. |