Các giới hạn và hạn mức 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. Các yêu cầu quá mức từ một API có thể là do lỗi chính tả vô hại hoặc 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ể sau 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 tình trạng tổng thể của hệ thống Google Workspace. Điều này giúp đả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 của phản hồi chứa 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 được đề xuất đối với các lỗi xảy ra do đạt đến hạn mức hạn mức.
| Mã | Lý do | Mô tả | Việc nên làm |
|---|---|---|---|
| 403 | userRateLimitExceeded | Cho biết người dùng đã vượt quá giới hạn tốc độ. 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 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 cách sử dụng tính năng tạm ngưng theo hàm mũ. |
| 403 | quotaExceeded | Cho biết đã đạ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 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 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 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 là trên mỗi tài khoản Google Workspace, chứ không phải trên 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
Thời gian đợi luỹ thừa là quá trình ứ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 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 yêu cầu đối với API
- Nhận được phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 1 giây +
random_number_millisecondsgiây - Thử lại yêu cầu
- Nhận được phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 2 giây +
random_number_millisecondsgiây - Thử lại yêu cầu
- Nhận được phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 4 giây +
random_number_millisecondsgiây - Thử lại yêu cầu
- Nhận được phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 8 giây +
random_number_millisecondsgiây - Thử lại yêu cầu
- Nhận được phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 16 giây +
random_number_millisecondsgiây - Thử lại yêu cầu
- 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á nhất định trong một số trường hợp triển khai đồng thời.
Bạn phải xác định lại random_number_milliseconds 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". Ứng dụng API của bạn có thể triển khai số lần thử nhiều hơn nếu cần.
Hạn mức và định mức 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 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ì 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 tối đa 10 phút để thông tin cập nhật được á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 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, số ký tự tối đa
|
Số ký tự tối đa cho thông tin vị trí của một thiết bị là 200. |
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 một thiết bị là 500. |
Thiết bị Chrome, tối đa user ký tự
|
Số ký tự tối đa cho tên người dùng thiết bị là 100. |
| 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 nội dung mô tả là 4.096. |
| Nhóm, theo tài khoản | Với tài khoản G Suite phiên bản cũ miễn 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 trên mỗi nhóm | Với tài khoản G Suite Phiên bản cũ miễn phí, 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 trong một nhóm. Để biết giới hạn về số lượng 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ố 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ố 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 bí danh người dùng đã xoá. |
| 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ẽ ảnh hưởng đến tiền bạc và sẽ 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 10 giấy phép Google Workspace được tính phí vào tài khoản của bạn, 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à 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ề 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 trường 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 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 dành cho quản trị viên. |
| 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 để 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 vào nhóm, các lựa chọn chia sẻ, hoạt động giám sát và bản lưu trữ cuộc thảo luận bằng Bảng điều khiển dành cho quản trị viên. Để 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 sử dụng sai mục đích email, Google giới hạn số lượng thư mà 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ư đế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ông báo không gửi được | 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ông báo trả về", đến một nhóm. |
| Các 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 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 để quản lý việc bật và tắt các 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ỳ. 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), 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 như 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 dưới dạng 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 đượ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 dành cho quản trị viên. Sử dụng thao tác Xoá bí danh của người dùng để xoá bí danh email sau khi đổi tên. |
| Người dùng trong nhiều miền | Một 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 tài khoản khác. Các thành phần miền 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 group1 là thành viên của group2, thì group2 không thể là thành viên của group1. |