API Lịch Google có hạn mức để đảm bảo rằng tất cả người dùng đều sử dụng API này một cách công bằng. Có 3 hạn chế quan trọng cần cân nhắc khi sử dụng Calendar API:
Hạn mức sử dụng API: Được thực thi theo từng dự án và từng người dùng. Để biết thêm thông tin, hãy xem phần Các loại hạn mức sử dụng API Lịch.
Giới hạn chung khi sử dụng Lịch Google: Google Calendar API là một dịch vụ dùng chung có các giới hạn để bảo vệ hiệu suất tổng thể của hệ thống Google Workspace. Để biết thêm thông tin, hãy xem bài viết Tránh vượt quá hạn mức sử dụng Lịch
Giới hạn về hoạt động: Các giới hạn này có thể bị hạn chế bất cứ lúc nào. Ví dụ: nếu bạn cố gắng ghi vào một lịch duy nhất trong thời gian ngắn.
Hạn mức Calendar API
Có 2 loại hạn mức được áp dụng:
Mỗi phút cho mỗi dự án: Đây là số lượng yêu cầu mà dự án Google Cloud của bạn có thể thực hiện trong một phút.
Mỗi phút trên mỗi người dùng trên mỗi dự án: Đây là số lượng yêu cầu mà một người dùng cụ thể có thể thực hiện trong dự án trên đám mây của bạn. Mức giới hạn này nhằm giúp bạn đảm bảo phân phối công bằng mức sử dụng cho người dùng.
Hạn mức được tính theo từng phút bằng cách sử dụng một cửa sổ trượt. Nếu lưu lượng truy cập tăng đột biến và vượt quá hạn mức mỗi phút trong một phút, thì bạn sẽ bị giới hạn tốc độ trong khoảng thời gian tiếp theo để đảm bảo rằng mức sử dụng trung bình của bạn vẫn nằm trong hạn mức.
Bảng sau đây trình bày chi tiết các hạn mức này:
| Loại hạn mức sử dụng | Hạn mức |
|---|---|
| Mỗi phút cho mỗi dự án | 10.000 yêu cầu |
| Mỗi phút cho mỗi người dùng trên mỗi dự án | 600 yêu cầu |
Ngưỡng thanh toán hằng ngày
Hạn mức mỗi ngày cho mỗi dự án này xác định số lượng yêu cầu tối đa mà dự án trên đám mây của bạn có thể sử dụng trong khoảng thời gian 24 giờ trước khi bị tính phí.
Nếu mức sử dụng dưới ngưỡng này, bạn sẽ không phải trả thêm phí và tài khoản Google Cloud của bạn sẽ không bị tính phí. Chúng tôi sẽ chia sẻ đầy đủ thông tin thanh toán vào cuối năm 2026 và thông báo trước ít nhất 90 ngày trước khi mọi thay đổi có hiệu lực.
Bạn không thể yêu cầu tăng giới hạn ngưỡng hằng ngày này.
Bảng sau đây trình bày chi tiết về giới hạn:
| Loại giới hạn ngưỡng | Hạn mức |
|---|---|
| Mỗi ngày cho mỗi dự án | 1.000.000 yêu cầu |
Để biết thêm thông tin, hãy xem Mô hình chuẩn hoá của Google Workspace cho các công cụ và API của nhân viên hỗ trợ.
Giải quyết lỗi hạn mức dựa trên thời gian
Đối với tất cả các lỗi dựa trên thời gian (tối đa N yêu cầu trong X phút), bạn nên để mã của mình bắt lỗi và sử dụng thuật toán giảm thời gian chờ theo hàm mũ bị cắt để đảm bảo thiết bị của bạn không tạo ra tải quá mức.
Thuật toán thời gian đợi luỹ thừa là một chiến lược xử lý sai số chuẩn cho các ứng dụng mạng. Thuật toán thời gian đợi luỹ thừa sẽ thử lại các yêu cầu bằng cách tăng thời gian chờ theo cấp số nhân giữa các yêu cầu, tối đa là thời gian đợi luỹ thừa. Nếu yêu cầu vẫn không thành công, thì điều quan trọng là độ trễ giữa các yêu cầu phải tăng theo thời gian cho đến khi yêu cầu thành công.
Thuật toán mẫu
Thuật toán thời gian đợi luỹ thừa sẽ thử lại các yêu cầu theo cấp số nhân, tăng thời gian chờ giữa các lần thử lại cho đến thời gian đợi tối đa. Ví dụ:
- Tạo một yêu cầu đối với API Lịch Google.
- Nếu yêu cầu không thành công, hãy đợi 1 +
random_number_millisecondsrồi thử lại yêu cầu. - Nếu yêu cầu không thành công, hãy đợi 2 +
random_number_millisecondsrồi thử lại yêu cầu. - Nếu yêu cầu không thành công, hãy đợi 4 +
random_number_millisecondsrồi thử lại yêu cầu. - Và cứ như vậy, tối đa
maximum_backofflần. - Tiếp tục chờ và thử lại cho đến khi đạt đến số lần thử lại tối đa, nhưng không tăng khoảng thời gian chờ giữa các lần thử lại.
trong đó:
- Thời gian chờ là
min(((2^n)+random_number_milliseconds), maximum_backoff), vớintăng thêm 1 cho mỗi lần lặp (yêu cầu). random_number_millisecondslà một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1.000. Điều này giúp tránh các trường hợp nhiều ứng dụng được đồng bộ hoá theo một số tình huống và tất cả đều thử lại cùng một lúc, gửi yêu cầu theo đợt đồng bộ hoá. Giá trị củarandom_number_millisecondsđược tính toán lại sau mỗi yêu cầu thử lại.maximum_backoffthường là 32 hoặc 64 giây. Giá trị phù hợp tuỳ thuộc vào trường hợp sử dụng.
Ứng dụng có thể tiếp tục thử lại sau khi đạt đến thời gian maximum_backoff.
Các lần thử lại sau thời điểm này không cần tiếp tục tăng thời gian tạm ngưng. Ví dụ: nếu một ứng dụng sử dụng thời gian maximum_backoff là 64 giây, thì sau khi đạt đến giá trị này, ứng dụng có thể thử lại sau mỗi 64 giây. Tại một thời điểm nào đó, các ứng dụng không được phép thử lại vô thời hạn.
Thời gian chờ giữa các lần thử lại và số lần thử lại tuỳ thuộc vào trường hợp sử dụng và điều kiện mạng của bạn.
Giá
Mọi hoạt động sử dụng API Lịch Google theo tiêu chuẩn đều không mất thêm phí. Việc vượt quá hạn mức yêu cầu dự kiến sẽ phát sinh phí cho tài khoản thanh toán Google Cloud của bạn vào cuối năm 2026. Để biết thêm thông tin, hãy xem Mô hình tiêu chuẩn của Google Workspace cho các công cụ và API của tác nhân.
Yêu cầu tăng hạn mức
Tuỳ thuộc vào mức sử dụng tài nguyên của dự án, bạn có thể muốn yêu cầu điều chỉnh hạn mức. Các lệnh gọi API của một tài khoản dịch vụ được coi là đang sử dụng một tài khoản duy nhất. Việc đăng ký hạn mức điều chỉnh không đảm bảo rằng bạn sẽ được phê duyệt. Các yêu cầu điều chỉnh hạn mức làm tăng đáng kể giá trị hạn mức có thể mất nhiều thời gian hơn để được phê duyệt.
Không phải dự án nào cũng có hạn mức giống nhau. Khi bạn ngày càng sử dụng Google Cloud, các giá trị hạn mức có thể cần tăng lên. Nếu dự kiến mức sử dụng sẽ tăng đáng kể trong thời gian tới, bạn có thể chủ động yêu cầu điều chỉnh hạn mức trên trang Hạn mức và giới hạn hệ thống trong bảng điều khiển Google Cloud.
Để tìm hiểu thêm, hãy xem các tài nguyên sau:
- Giới thiệu về việc điều chỉnh hạn mức
- Xem mức sử dụng và hạn mức của bạn
- Yêu cầu tăng hạn mức sử dụng
Khắc phục sự cố
Nếu vượt quá một trong hai hạn mức này, bạn sẽ bị giới hạn tốc độ và nhận được mã trạng thái 403
usageLimits hoặc mã trạng thái 429
usageLimits để phản hồi các truy vấn của bạn.
Nếu điều này xảy ra, bạn có thể thử làm như sau:
Hãy nhớ làm theo tất cả các phương pháp hay nhất: sử dụng thuật toán tăng tốc luỹ thừa, tạo mẫu lưu lượng truy cập ngẫu nhiên và sử dụng thông báo đẩy.
Nếu dự án của bạn đang phát triển và có nhiều người dùng hơn, bạn có thể yêu cầu tăng hạn mức.
Nếu đạt đến hạn mức cho mỗi người dùng, bạn có thể làm những việc sau:
Nếu bạn sử dụng tài khoản dịch vụ, hãy phân bổ tải cho người dùng hoặc chia tải giữa nhiều tài khoản dịch vụ.
Mặc dù bạn có thể yêu cầu tăng hạn mức cho mỗi người dùng, nhưng nói chung, bạn không nên tăng hạn mức này lên trên giá trị mặc định vì ứng dụng của bạn có thể bắt đầu gặp phải các loại hạn mức khác, chẳng hạn như hạn mức sử dụng lịch chung hoặc hạn mức hoạt động.
Kiểm thử hạn mức bằng cách đăng ký một dự án riêng chỉ dành cho kiểm thử có cấu hình tương tự như dự án sản xuất của bạn. Để biết thêm thông tin, hãy xem phần Xử lý giới hạn hạn mức kiểm thử.
Tạo ngẫu nhiên các mô hình giao thông
Các ứng dụng lịch có xu hướng có các mẫu lưu lượng truy cập đột biến do nhiều ứng dụng thực hiện các thao tác cùng một lúc. Ví dụ: một phương pháp hay thường thấy nhưng không nên áp dụng đối với ứng dụng Lịch là thực hiện đồng bộ hoá toàn bộ vào lúc nửa đêm. Điều này gần như chắc chắn sẽ dẫn đến việc vượt quá hạn mức mỗi phút và dẫn đến tình trạng giới hạn tốc độ và thời gian chờ.
Để tránh điều này, hãy đảm bảo rằng lưu lượng truy cập của bạn được phân bổ trong suốt cả ngày bất cứ khi nào có thể. Nếu ứng dụng khách của bạn cần đồng bộ hoá hằng ngày, hãy để ứng dụng khách xác định một thời gian ngẫu nhiên (khác nhau đối với mỗi ứng dụng khách). Nếu bạn cần thực hiện một thao tác thường xuyên, hãy thay đổi khoảng thời gian +/- 25%. Điều này sẽ phân phối lưu lượng truy cập đồng đều hơn và mang lại trải nghiệm tốt hơn nhiều cho người dùng.
Sử dụng thông báo đẩy
Một trường hợp sử dụng phổ biến là thực hiện một hành động bất cứ khi nào có thay đổi trong lịch của người dùng. Một mẫu chống lại ở đây là liên tục thăm dò mọi lịch mà bạn quan tâm. Thao tác này sẽ nhanh chóng sử dụng hết hạn mức của bạn. Ví dụ: nếu ứng dụng của bạn có 5.000 người dùng và mỗi phút thăm dò lịch của từng người dùng một lần, thì ứng dụng này yêu cầu hạn mức mỗi phút ít nhất là 5.000, ngay cả trước khi thực hiện bất kỳ thao tác nào.
Các ứng dụng phía máy chủ có thể đăng ký nhận thông báo đẩy, nhờ đó chúng tôi có thể thông báo cho bạn khi có điều gì đó thú vị xảy ra. Những phương thức này đòi hỏi nhiều công sức hơn để thiết lập, nhưng cho phép sử dụng hạn mức hiệu quả hơn đáng kể và mang lại trải nghiệm tốt hơn cho người dùng. Đảm bảo rằng bạn chỉ định eventType mà bạn muốn nhận thông báo. Để biết thêm thông tin, hãy xem bài viết Thông báo đẩy.
Phân bổ thích hợp bằng tài khoản dịch vụ
Nếu ứng dụng của bạn đang thực hiện các yêu cầu bằng cách sử dụng cơ chế uỷ quyền trên toàn miền, thì theo mặc định, tài khoản dịch vụ sẽ bị tính phí liên quan đến hạn mức "mỗi phút cho mỗi người dùng cho mỗi dự án", chứ không phải người dùng mà bạn đang mạo danh. Điều này có nghĩa là tài khoản dịch vụ có thể hết hạn mức và bị giới hạn tốc độ, ngay cả khi tài khoản đó có thể đang hoạt động trên lịch của nhiều người dùng.
Bạn có thể tránh trường hợp này bằng cách sử dụng tham số URL quotaUser (hoặc tiêu đề HTTP x-goog-quota-user) để cho biết người dùng nào bị tính phí. Thông số này chỉ được dùng để tính hạn mức. Để biết thêm thông tin, hãy xem phần Giới hạn số yêu cầu trên mỗi người dùng.
Xử lý hạn mức thử nghiệm
Để đảm bảo ứng dụng của bạn có thể xử lý một cách hiệu quả việc đạt đến hạn mức trong thực tế (ví dụ: thông qua thử lại với độ trễ tăng dần) và giảm thiểu mọi sự gián đoạn có thể xảy ra cho người dùng, bạn nên kiểm thử tình huống của mình trong một môi trường thực.
Để kiểm thử mà không ảnh hưởng đến việc sử dụng ứng dụng thực tế, bạn nên đăng ký một dự án chỉ dành cho kiểm thử riêng biệt trong bảng điều khiển Cloud, sau đó định cấu hình màn hình xin phép bằng OAuth theo cách tương tự như dự án phát hành công khai của bạn. Sau đó, bạn có thể đặt hạn mức thấp giả tạo cho dự án này và quan sát hành vi của ứng dụng.