用量限额和配额
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
限制和配额可保护 Google 基础架构免受自动进程以不当方式使用 Data Transfer API 的影响。来自 API 的过多请求可能是由无害的拼写错误所致,也可能是由于系统设计效率低下、进行不必要的 API 调用而导致的。无论出于何种原因,在来自特定来源的流量达到特定级别时,都必须屏蔽该流量,这样才能确保 Google Workspace 系统的整体运行状况。它可确保一个开发者的行为不会对更大的社区产生负面影响。
API 请求失败
在极少数情况下,如果您的 API 请求失败,您的应用会收到 HTTP 状态代码响应。状态代码 403
包含有关错误输入的错误信息;HTTP 状态代码 503
则包含错误信息,指明已超出哪些 API 配额。通过这些响应,您的自定义应用可检测这些错误并采取适当的措施。
在固定时间段内完成请求
如果您的请求需要在固定时间段内完成,请并行发送请求,或在 Java 或 C# 应用中使用多个线程。例如,按月或其他时间段细分您的请求。对于线程,请尝试从 10 个线程开始,每个请求一个线程。线程建议需要权衡利弊,并且并非适用于所有 API 情况。如果请求数太高,将发生配额错误。
基于时间的错误
对于基于时间的所有错误(每个线程最多显示 N 个 X 秒的错误),尤其是 503
状态代码错误,我们建议您的代码捕获异常,并使用指数退避算法算法,等待一小段延迟后再重试失败的调用。一个线程的 Data Transfer API 示例是等待 5 秒,然后重试失败的调用。如果请求成功,则对其他线程重复此模式。如果第二个请求未成功,您的应用应根据请求频率缩容,直到调用成功为止。例如,将最初 5 秒的延迟时间增加到 10 秒,然后重试失败的呼叫。此外,您需要决定重试限制。例如,在您的应用向用户返回错误之前,使用不同的延迟时间重试请求 5 到 7 次。
限制
API 限制类别 |
限制 |
每秒查询数 (QPS) |
开发者项目的上限为每个帐号每秒 10 次查询 (QPS)。 |
配额
API 配额类别 |
配额 |
每天的 API 请求数上限 |
每天的最大 API 请求数为 500,000。 |
归档,邮件过期 |
群组归档不会过期。在群组被删除之前,邮件会一直保留在归档中。电子邮件保留政策不会影响群组归档中的邮件。 |
邮件大小 |
邮件的大小上限为 25MB。此限制包括消息的元数据标头、正文和所有附件。 |
其他类型的限制
其他类型的限制 |
限制和准则 |
内容类型格式 |
电子邮件必须采用标准 RFC 822 文本格式。请求的内容类型格式(用于上传已迁移的电子邮件)使用 Content-type: message/rfc822 标头。 |
API 响应中的数据格式 |
响应的数据格式为 JavaScript 对象表示法 (JSON)。 |
数据位置政策 |
Data Transfer API 不支持因合同原因而要求将数据存储在特定地理边界或政治边界内的数据位置政策。如果您的帐号需要数据位置,请勿使用 Data Transfer API。 |
并行消息插入 |
Data Transfer API 支持以并行请求将电子邮件插入不同群组归档。但是,Data Transfer API 不支持将消息并行插入同一组归档文件。此版本的 API 也不支持批量请求。 |
未经授权的请求 |
Data Transfer API 不接受任何未经授权的请求。如果未提供授权令牌,请求将被视为未授权。
|
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-29。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[],[],null,["# Usage limits and quotas\n\nLimits and quotas protect the Google infrastructure from an automated process that uses the\nData Transfer API in an inappropriate way. Excessive requests from an API might result from a\nharmless typo, or might result from an inefficiently designed system that makes needless API\ncalls. Regardless of the cause, blocking traffic from a specific source when it reaches a certain\nlevel is necessary for the overall health of the Google Workspace system. It ensures that one\ndeveloper's actions can't negatively impact the larger community.\n\nAPI request failures\n--------------------\n\nIn the unlikely event that your API request fails, your application receives an HTTP status code\nresponse. A status code of `403` has error information about incorrect input, and an\nHTTP status code of `503` has error information indicating which API quotas have been\nexceeded. These responses let your custom application detect these errors and take appropriate\naction.\n\nComplete requests in a fixed time period\n----------------------------------------\n\nIf your requests need to be completed in a fixed period of time, send your requests in parallel\nor use multiple threads in your Java or C# application. For example, break your requests by month\nor another time period. In the case of threads, try starting with 10 threads, one thread per\nrequest. The thread recommendation has trade-offs and isn't useful for all API situations. If the\nnumber of requests gets too high, quota errors will occur.\n\nTime-based errors\n-----------------\n\nFor all errors that are time based (maximum of N things for X seconds per thread), especially the\n`503` status code errors, we recommend that your code catch the exception and by using\nan\n[exponential backoff](http://wikipedia.org/wiki/Truncated_binary_exponential_backoff)\nalgorithm, wait for a small delay before retrying the failed call. A Data Transfer API example\nfor one thread is to wait 5 seconds and retry the failed call. If the request is successful,\nrepeat this pattern for the other threads. If the second request is not successful, your\napplication should scale back on the frequency of the request until a call is successful. For\nexample, increase the initial 5 second delay to 10 seconds and retry your failed call again. Also,\ndecide on a retry limit. For example retry a request 5 to 7 times with different delay times\nbefore your application returns an error to the user.\n\nLimits\n------\n\n| API limit categories | Limits |\n|--------------------------|-------------------------------------------------------------------------|\n| Queries per second (QPS) | The developer project limit is 10 queries per second (QPS) per account. |\n\nQuotas\n------\n\n| API quota categories | Quotas |\n|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Maximum API requests per day | The maximum API requests per day is 500,000. |\n| Archive, expiration of messages | Group archives don't expire. Messages remain in an archive until the group is deleted. The email retention policy doesn't affect messages in a group's archive. |\n| Mail message size | The maximum mail message size is 25MB. This limit includes the message's meta data headers, body, and any attachments. |\n\nOther types of limits\n---------------------\n\n| Other types of limits | Limitations and guidelines |\n|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Content type formats | An email message must be in the standard [RFC 822 text format](http://www.w3.org/Protocols/rfc822/). A request's content-type format for uploading migrated emails use the `Content-type: message/rfc822` header. |\n| Data format in API responses | The response's data format is Javascript Object Notation ([JSON](http://json.org/)). |\n| Data location policies | The Data Transfer API doesn't support data location policies requiring data be stored in specific geographic or political boundaries for contractual reasons. Don't use the Data Transfer API if data location is required for your account. |\n| Parallel message insertions | The Data Transfer API supports parallel requests for email insertions into different group archives. But the Data Transfer API doesn't support parallel message insertions into the same group archive. Nor are batch requests supported in this version of the API. |\n| Unauthorized requests | The Data Transfer API doesn't accept any unauthorized requests. A request is considered unauthorized if no authorization token is provided. |"]]