Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Hạn mức sử dụng

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. Hãy cân nhắc 3 hạn chế quan trọng 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 Calendar API.
Giới hạn chung về mức sử dụng Lịch: 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 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ể được áp dụng bất cứ lúc nào. Ví dụ: có thể có giới hạn 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 trên đám mây của bạn trên Google Cloud 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. Hạn mức này giúp đảm bảo việc phân bổ mức sử dụng một cách công bằ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. Lượng lưu lượng truy cập tăng đột biến vượt quá hạn mức mỗi phút sẽ dẫn đến việc 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 hạn mức tối đa	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 tiêu chuẩn của Google Workspace cho các công cụ và API của đặc vụ.

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ũ để đảm bảo thiết bị 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_milliseconds rồ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_milliseconds rồ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_milliseconds rồi thử lại yêu cầu.
Và cứ như vậy, tối đa maximum_backoff lầ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ới n tăng thêm 1 cho mỗi lần lặp (yêu cầu).
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 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ủa random_number_milliseconds được tính toán lại sau mỗi yêu cầu thử lại.
maximum_backoff thườ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. Sau thời điểm này, các lần thử lại 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 sẽ 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 yêu cầu điều chỉnh hạn mức không đảm bảo rằng yêu cầu sẽ được phê duyệt. Những 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 Google Cloud console.

Để tìm hiểu thêm, hãy xem các tài nguyên sau:

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, trộn lẫn các mẫu lưu lượng truy cập 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ể 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 phát hành công khai. Để 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 bị mắc lỗi thường gặp đố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 thường vượt quá hạn mức mỗi phút của bạn và gây ra tình trạng giới hạn tốc độ và thời gian chờ.

Để tránh tình trạng này, hãy phân bổ lưu lượng truy cập trong suốt cả ngày nếu 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 giúp 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 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. Điều này sẽ nhanh chóng làm cạn kiệ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à thăm dò lịch của mỗi người dùng một lần mỗi phút, 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ỳ công việ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ờ đó, Lịch có thể thông báo cho bạn khi có sự kiện mà bạn quan tâm. Những phương thức này đòi hỏi bạn phải bỏ ra nhiều công sức hơn để thiết lập, nhưng cho phép bạn sử dụng hạn mức hiệu quả hơn và mang lại trải nghiệm tốt hơn cho người dùng. 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 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ẽ được tính vào 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 nhập vai. Điều này có nghĩa là tài khoản dịch vụ có thể sẽ hết hạn mức và bị giới hạn tốc độ, ngay cả khi tài khoản đó có thể 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í. Google chỉ sử dụng tham số này để 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 rằng ứng dụng của bạn xử lý một cách linh hoạt việc đạt đến hạn mức trong thực tế (ví dụ: thông qua các lần thử lại với thuật toán thời gian đợi luỹ thừa) và để giảm thiểu mọi sự gián đoạn tiềm ẩn cho người dùng, hãy kiểm thử ứng dụng của bạn trong một môi trường thực tế.

Để kiểm thử mà không ảnh hưởng đến việc sử dụng ứng dụng thực tế, hãy đăng ký một dự án chỉ dành cho kiểm thử riêng biệt trong Google Cloud Console, sau đó định cấu hình màn hình yêu cầu đồng ý OAuth theo cách tương tự như dự án phát hành 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.

Hạn mức máy chủ MCP của Lịch

Máy chủ MCP Lịch sử dụng chỉ số phân bổ chi phí truy vấn. Các bảng sau đây trình bày chi tiết chi phí truy vấn cho từng phương thức máy chủ MCP Lịch theo phần:

Hạn mức MCP của lịch