Hạn mức và hạn ngạch 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. Số lượng yêu cầu quá nhiều từ một API có thể là do lỗi đánh máy vô hại hoặc do hệ thống được thiết kế không hiệu quả, 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ì, 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à điều cần thiết để đảm bảo tình trạng tổng thể của hệ thống Google Workspace. Điều 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, nội dung 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 các mã lỗi, lý do, 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 | Mô tả | Việc nên làm |
|---|---|---|---|
| 403 | userRateLimitExceeded | Cho biết đã vượt quá giới hạn số lượng yêu cầu của 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 trên mỗi dự án trên đám mây của Google Cloud. | Tăng hạn mức cho 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 trên đám mây Google, 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 đợi tăng dần. |
| 403 | quotaExceeded | Cho biết rằng đã đạt đến giới hạn 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 cần giảm tốc độ gửi yêu cầu. |
| 429 | rateLimitExceeded | Cho biết đã đạt đến giới hạn 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. Hạn mức 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à quá trình ứng dụng thực hiện hoạt động thử lại định kỳ đối vớ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 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.
- Tạo một yêu cầu đối với API
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 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
- Chờ 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
- Chờ 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
- Chờ 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 1.000. Điều này là cần thiết để tránh một số lỗi khoá trong một số phương thức 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ỉ nhằm 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". Ứng dụng API của bạn có thể triển khai số lần thử cao 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 |
|---|---|
| Đang 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 API Thư mục. |
| Xoá người dùng | Bạn có thể xoá tối đa 5 người dùng trên mỗi miền mỗi giây bằng API Thư mục. Đây là hạn mức dịch vụ phụ trợ cho mỗi miền và không thể điều chỉnh trong hạn mức dự án của Google Cloud Console. Khi gửi yêu cầu hàng loạt, hãy đảm bảo tổng số thao tác trên các lô luôn dưới 5 truy vấn mỗi giây (QPS). |
| Xoá thành viên trong nhóm | Bạn có thể xoá tối đa 30 thành viên nhóm cho mỗi miền mỗi giây bằng Directory API. Đây là hạn mức dịch vụ phụ trợ cho mỗi miền và không thể điều chỉnh trong hạn mức dự án của Google Cloud Console. Khi gửi yêu cầu hàng loạt, hãy đảm bảo tổng số thao tác trên các lô luôn dưới 30 truy vấn mỗi giây (QPS). |
| 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 dưới dạng thành viên của nhóm mẹ. Giới hạn này có thể thay đổi tuỳ theo tài nguyên hệ thống. |
| 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 và dịch vụ của trình duyệt. Để biết thêm thông tin, hãy xem bài viết Cập nhật người dùng. |
| Đang 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, số ký tự tối đa
|
Thông tin vị trí của thiết bị có tối đa 200 ký tự. |
Thiết bị Chrome notes, số ký tự tối đa
|
Số 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 của 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ố 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 được 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. |
| Số nhóm, số thành viên mỗi nhóm | Đối với 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 giới hạn số lượng thành viên trong một nhóm. Để biết giới hạn về số nhóm mà mỗi người dùng có thể tham gia, 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 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. Ngoài ra, đị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ố email đại diện đượ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 bí danh người dùng đã xoá. |
| Các loại hạn mức khác | Các hạn chế 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 tiền và dẫn đến các khoản phí cho 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 xong. Nếu đang dùng gói hằng năm, bạn đã cam kết thanh toán 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, hãy xem trung tâm trợ giúp dành cho quản trị viên. |
| Họ và tên | Tên và họ có tối đa 40 ký tự. Các nhãn 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 (/) 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 dành cho quản trị viên. |
| Nhóm, đang xoá | 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 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 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 thành viên nhóm. Sau khi thay đổi, API sẽ tự động phản ánh các thay đổi về địa chỉ email. |
| Nhóm, chế độ cài đặt | Bạn có thể quản lý chế độ cài đặt quyền truy cập, 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ủa nhóm 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 lạm dụng 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ư đến 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ư NDR | Bạn không thể gửi hoặc chuyển tiếp thông báo không gửi được (NDR), còn gọi là "thư bị trả lại", đến một nhóm. |
| Nhóm do người dùng tạo, các giới hạn | Để biết giới hạn về nhóm do người dùng tạo, hãy xem trung tâm trợ giúp dành cho quản trị viên |
| Đơ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 tổ hợp ký tự bất kỳ. Mật khẩu phải có í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 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 (.). Đ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 dành cho quản trị viên. |
| 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 đổi tên. Người dùng phải yêu cầu cấp quyền để trò chuyện lại với bạn bè. Tên người dùng cũ đượ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 có chế độ cài đặt chuyển tiếp email và sẽ không dùng được 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 dành cho quản trị viên. 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 ở 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. Các thành phần của nhiều miền là:
|
| Cảnh báo, thành viên trong nhóm | GROUP_CANNOT_CONTAIN_CYCLE – API không cho phép 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. |