Hạn mức sử dụng

Gmail API có hạn mức sử dụng, hạn chế tốc độ gọi các phương thức của API. Giới hạn được xác định theo đơn vị hạn mức, một đơn vị đo lường trừu tượng thể hiện mức sử dụng tài nguyên của Gmail.

Hạn mức API Gmail

Có 2 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à số lượng đơn vị hạn mức mà dự án trên đám mây của bạn có thể sử dụng 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 đơn vị hạn mức mà một người dùng cụ thể có thể sử dụng 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 phân phối công bằng mức sử dụng cho người dùng.

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 1.200.000 đơn vị hạn mức
Mỗi phút cho mỗi người dùng trên mỗi dự án 6.000 đơn vị hạn mức

Để biết thông tin về cách xử lý lỗi liên quan đến hạn mức, hãy xem bài viết Giải quyết lỗi.

Ngưỡng thanh toán hằng ngày

Giới hạn mỗi ngày cho mỗi dự án này xác định số lượng đơn vị hạn mức 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 80.000.000 đơn vị hạn mức

Để 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ợ.

Hạn mức sử dụng theo phương thức

Số lượng đơn vị hạn mức được sử dụng cho mỗi yêu cầu sẽ khác nhau tuỳ thuộc vào phương thức được gọi. Bảng sau đây trình bày mức sử dụng hạn mức theo từng phương thức:

Phương thức Các đơn vị hạn ngạch
drafts.create 10
drafts.delete 10
drafts.get 20
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 20
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 20
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 20
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get 40
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

Khi sử dụng API Gmail, bạn cũng bị giới hạn số lượng người nhận là 500 người cho mỗi nội dung email.

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ụ:

  1. Tạo một yêu cầu đối với API Gmail.
  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ứ như vậy, tối đa maximum_backoff lần.
  6. 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. 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 Gmail API 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: