Hạn mức sử dụng

API Lịch Google có hạn mức để đảm bảo tất cả người dùng đều sử dụng API này một cách công bằng. Có ba hạn chế quan trọng cần lưu ý khi sử dụng Calendar API:

  • Hạn mức sử dụng API: Được áp dụng cho mỗi dự án và mỗi người dùng. Để biết thêm thông tin, hãy xem Các loại hạn mức sử dụng API Lịch.

  • Giới hạn sử dụng chung của Lịch Google: API Lịch Google 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

  • Hạn mức hoạt động: Những hạn mức này có thể bị giới hạn bất cứ lúc nào. Ví dụ: nếu bạn cố gắng ghi vào một lịch liên tiếp nhanh chóng.

Hạn mức API Lịch

Có hai 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. Hạn mức này nhằm giúp bạn đả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 phút bằng cách sử dụng cửa sổ trượt. Lưu lượng truy cập tăng đột biến vượt quá hạn mức mỗi phút trong một 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 giới hạn này:

Loại hạn mức sử dụng Hạn mức
Mỗi phút 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 Google Cloud của bạn có thể sử dụng trong khoảng thời gian 24 giờ trước khi áp dụng phí.

Mức sử dụng dưới ngưỡng này sẽ không phát sinh thêm phí và tài khoản Google Cloud của bạn sẽ không bị tính phí. Thông tin chi tiết đầy đủ về việc thanh toán sẽ được chia sẻ vào cuối năm 2026, í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 ngưỡng giới hạn hằng ngày này.

Bảng sau đây trình bày chi tiết về hạn mức:

Loại ngưỡng giới hạn Hạn mức
Mỗi ngày mỗi dự án 1.000.000 yêu cầu

Để biết thêm thông tin, hãy xem bài viết Mô hình chuẩn hoá của Google Workspace cho các công cụ và API của tác nhân.

Giải quyết lỗi hạn mức theo thời gian

Đối với tất cả lỗi dựa trên thời gian (tối đa N yêu cầu mỗi X phút), bạn nên để mã của mình phát hiện ngoại lệ và sử dụng thuật toán thời gian đợi luỹ thừa bị cắt bớ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 luỹ thừa giữa các yêu cầu, cho đến thời gian đợi tối đ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 dần 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 luỹ thừa, tăng thời gian chờ giữa các lần thử lại cho đến khi đạt thời gian đợi tối đa. Ví dụ:

  1. Tạo yêu cầu đến API Lịch Google.
  2. 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.
  3. 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.
  4. 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.
  5. Và cứ tiếp tục như vậy, tối đa maximum_backoff lần.
  6. Tiếp tục chờ và thử lại cho đến khi đạt số lần thử lại tối đa, nhưng không tă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 trường hợp nhiều ứng dụng khách đượ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 các đợ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 phụ 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 đợi. Ví dụ: nếu ứng dụng khách sử dụng thời gian maximum_backoff là 64 giây, thì sau khi đạt đến giá trị này, ứng dụng khách có thể thử lại sau mỗi 64 giây. Tại một thời điểm nào đó, bạn nên ngăn ứng dụng 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 phụ 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 thông thường đối với API Lịch Google đều không mất thêm phí. Nếu vượt quá giới hạn yêu cầu về hạn mức, bạn sẽ phải trả phí cho tài khoản thanh toán trên Google Cloud vào cuối năm 2026. Để 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 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ể 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à 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. Những yêu cầu điều chỉnh hạn mức có thể 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 sử dụng Google Cloud ngày càng nhiều theo thời gian, giá trị hạn mức của bạn có thể cần phải 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, 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:

  1. 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 đợi thời gian luỹ thừa, ngẫu nhiên hoá các mẫu lưu lượng truy cập và sử dụng thông báo đẩy.

  2. Nếu dự án của bạn đang phát triển và bạn có nhiều người dùng hơn, bạn có thể yêu cầu tăng hạn mức.

  3. Nếu đạt đến hạn mức cho mỗi người dùng, bạn có thể làm như 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 nhìn chung, bạn không nên tăng hạn mức này lên cao hơn giá trị mặc định vì ứng dụng của bạn có thể bắt đầu đạt đến 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.

  4. Kiểm tra hạn mức của bạn bằng cách đăng ký một dự án riêng chỉ dùng để kiểm thử có cấu hình tương tự như dự án chính thức. Để biết thêm thông tin, hãy xem phần Kiểm thử cách xử lý hạn mức.

Sắp xếp ngẫu nhiên các mô hình lưu lượng truy cập

Ứng dụng Lịch dễ gặp phải các mẫu lưu lượng truy cập tăng độ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 không hay 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 gần như chắc chắn sẽ khiến bạn vượt quá hạn mức mỗi phút, dẫn đến việc giới hạn tốc độ và thời gian đợi.

Để 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ần đồng bộ hoá hằng ngày, hãy yêu cầu ứng dụng khách xác định một thời điểm ngẫu nhiên (khác nhau cho 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ẽ 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 phản mẫu ở đây là liên tục thăm dò ý kiến của mọi lịch mà bạn quan tâm. Việ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à thăm dò ý kiến lịch của mỗi người dùng một lần mỗi phút, thì việc này đòi hỏi hạn mức mỗi phút ít nhất là 5.000, ngay cả trước khi hoàn tất 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, cho phép chúng tôi thông báo cho bạn khi có điều gì đó thú vị xảy ra. Các phương pháp này đòi hỏi bạn phải thiết lập nhiều hơn, nhưng cho phép bạn 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. Hãy nhớ chỉ định eventType mà bạn muốn nhận thông báo. Để biết thêm thông tin, hãy xem phần Thông báo đẩy.

Phân bổ đúng cách 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 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í theo 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ể sẽ 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 điều này bằng cách sử dụng tham số URL quotaUser (hoặc tiêu đề HTTP x-goog-quota-user) để chỉ định một chuỗi tuỳ ý (tối đa 40 ký tự) giúp xác định riêng biệt từng người dùng. Calendar API chỉ sử dụng giá trị này để tính hạn mức.

Để sử dụng quotaUser nhằm thực thi giới hạn số lượng yêu cầu cho mỗi người dùng đối với những người dùng riêng biệt, các yêu cầu của bạn phải đáp ứng những yêu cầu sau:

  • Thêm khoá API bị hạn chế theo IP: Truyền khoá API trong tham số truy vấn key và định cấu hình khoá đó bằng quy tắc hạn chế theo địa chỉ IP, trong đó chỉ định địa chỉ IP công khai của máy chủ phụ trợ. Nếu bạn bỏ qua khoá API hoặc không định cấu hình các quy định hạn chế về địa chỉ IP, thì Calendar API sẽ bỏ qua quotaUser và tính hạn mức cho tài khoản đã xác thực (chẳng hạn như tài khoản dịch vụ).

  • Bỏ qua tiêu đề X-Goog-User-Project: Đừng gửi tiêu đề HTTP X-Goog-User-Project trong các yêu cầu sử dụng quotaUser. Việc cung cấp dự án người dùng sẽ ghi đè khoá API để phân bổ hạn mức, vì vậy, API Lịch sẽ bỏ qua quotaUser.

Để biết thêm thông tin, hãy xem phần Giới hạn số lượng yêu cầu cho mỗi người dùng.

Kiểm thử cách xử lý hạn mức

Để đảm bảo ứng dụng của bạn có thể xử lý một cách linh hoạt khi đạt đến hạn mức trong thực tế (ví dụ: thông qua thử lại bằng thuật toán thời gian đợi luỹ thừa) 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 thử nghiệm tình huống của mình trong môi trường thực tế.

Để thử nghiệm 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 riêng chỉ dành cho thử nghiệm trong Google Cloud Console, 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. 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 của 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 của máy chủ MCP cho Lịch theo phần:

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

Có hai loại hạn mức được áp dụng:

  • Mỗi phút cho mỗi dự án trên đám mây: Đây là chi phí truy vấn cho dự án Google Cloud của bạn trong một phút.

  • Mỗi phút cho mỗi người dùng trên mỗi dự án: Đây là chi phí truy vấn cho dự án trên đám mây của bạn trong một phút mà bất kỳ người dùng cụ thể nào cũng có thể sử dụng.

Bảng sau đây trình bày chi tiết về các hạn mức này:

Loại hạn mức sử dụng Chi phí truy vấn
Mỗi phút mỗi dự án 10.000
Mỗi phút cho mỗi người dùng trên mỗi dự án 600

Hạn mức của bộ công cụ MCP cho Lịch

Bảng sau đây trình bày chi tiết chi phí truy vấn cho từng calendarmcp.googleapis.com bộ công cụ:

Điểm cuối Công cụ Chi phí truy vấn

/mcp/v1

create_event

1

delete_event

10

get_event

1

list_events

1

respond_to_event

1

search_events

1

update_event

1

suggest_time

1

list_calendars

1

Để biết thêm thông tin, hãy xem Tài liệu tham khảo về API MCP của Lịch.