Data API 限制和配额

以下限制和配额适用于 Data API。

配额的应用方式

对 Google Analytics Data API v1 发出的所有请求都需要 Google Cloud 项目，并且受此页面上列出的配额限制。无论使用哪种方法来识别调用项目，配额都会被消耗，包括：

• 使用 OAuth 2.0 凭据进行身份验证的请求。
• 仅使用 API 密钥进行身份验证的请求。

API 密钥用于将请求与特定的 Google Cloud 云项目关联，以用于配额和结算。使用项目中的凭据或 API 密钥发出的所有 API 调用都将计入项目和 Google Analytics 媒体资源的适用配额。

配额类别

Data API 有四种请求配额类别：核心、实时、漏斗图和聊天。

对核心方法的 API 请求会消耗核心配额。对实时方法的 API 请求会消耗实时配额。对漏斗图方法的 API 请求会消耗漏斗图配额。对聊天方法的 API 请求会消耗聊天配额。每个请求仅消耗一种配额。

Google Analytics 媒体资源配额

所有请求都会消耗媒体资源配额。

• 并发请求数是指同时执行的请求数。如需减少请求并发数，请等待之前的请求完成，然后再发送其他请求。
• 服务器错误是指 500 和 503 代码。只有当请求导致服务器错误时，才会消耗服务器错误配额。当项目和媒体资源对的服务器错误配额耗尽时，来自该项目的所有对该媒体资源的请求都会被屏蔽。如需查看错误响应的完整列表，请参阅错误 响应。
• 每个请求都会消耗“每项媒体资源每小时的令牌数”和“每个项目每项媒体资源每小时的令牌数”配额。这意味着，一项媒体资源必须被 3 个以上的项目访问，“每项媒体资源每小时的令牌数”配额才有可能在“每个项目每项媒体资源每小时的令牌数”配额之前耗尽。

媒体资源每小时最多可以发出 120 个可能受阈值限制的请求。userAgeBracket、userGender、brandingInterest、audienceId 和 audienceName 维度可能会受到阈值限制。我们之所以应用阈值，是为了防止查看报告的人通过其中的数据推断出具体用户的受众特征或兴趣。

媒体资源令牌配额

每次向 Google Analytics Data API v1 发出请求时，都会消耗令牌。 消耗的令牌数量取决于请求的复杂程度。虽然大多数 请求会消耗 10 个或更少的令牌，但更复杂的请求（例如 Ask Advisor chat 查询）会消耗更多令牌。

影响令牌消耗的因素

请求的确切令牌费用是在执行时确定的，因此很难进行精确的预计算。费用受与请求本身以及 Google Analytics 媒体资源中的底层数据相关的一系列因素的影响。以下因素可能会导致费用增加：

• 行数 ：请求的行数越多。
• 维度和指标的数量 ：包含的维度和指标越多。
• 过滤条件的复杂程度 ：采用复杂的过滤表达式。
• 日期范围的长度 ：查询的日期范围越长。
• 数据基数 ：基数较高的维度（例如 pagePath、自定义维度等具有许多唯一值的维度）可能会显著增加令牌费用。
• 媒体资源事件量 ：与数据较少的媒体资源上的相同查询相比，事件量较高的媒体资源上的查询可能会消耗更多令牌。

监控令牌使用情况

确定特定 API 调用的令牌费用的最有效方法 是在请求正文中添加参数 "returnPropertyQuota": true （ runReport、 batchRunReports、 runPivotReport、 batchRunPivotReports、 runRealtimeReport 和 runFunnelReport 中支持此参数）。然后， API 响应将包含 PropertyQuota 对象，其中详细说明了该 特定请求消耗的令牌以及剩余的配额余额。

包含 returnPropertyQuota 的示例请求

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}

示例 propertyQuota 响应载荷

当 "returnPropertyQuota": true 设置为 true 时，响应会包含一个 propertyQuota 对象，其中每个字段 包含一个 QuotaStatus，其中包含 consumed 和 remaining 整数：

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

propertyQuota 中的每个字段都对应于 Google Analytics 媒体资源配额 中的一个配额。单个 API 请求的令牌费用会同时从 tokensPerDay、tokensPerHour 和 tokensPerProjectPerHour 中扣除。如果任何配额存储桶的剩余令牌数达到 0，则后续对该媒体资源的请求会返回 429 RESOURCE_EXHAUSTED 错误。

避免 429 RESOURCE_EXHAUSTED 错误的最佳实践

• 动态监控 remaining 余额：检查响应中的 propertyQuota.tokensPerProjectPerHour.remaining 和 propertyQuota.tokensPerHour.remaining，并在剩余令牌数低于安全 阈值时限制或暂停 非紧急后台作业。
• 批量处理相关查询：使用 batchRunReports或 batchRunPivotReports 将最多 5 个报告分组到单个 HTTP 调用中，并减少 HTTP 往返 开销（请注意，批处理中的每个报告仍会单独计入令牌和 concurrentRequests配额）。
• 降低查询复杂性和基数 ：仅请求所需的维度和指标，尽可能缩短 dateRanges，并避免在频繁轮询查询中组合多个高基数维度（例如 pagePath 或 fullPageUrl）。
• 控制请求并发数 ：对请求进行排队或限制工作器池大小，以使正在处理的请求数保持在 concurrentRequests 限制（标准版为 10，Analytics 360 为 50）以下。
• 实现具有重试限制的指数退避算法：如果请求因 429 RESOURCE_EXHAUSTED、500 INTERNAL 或 503 UNAVAILABLE 而失败，请按照错误响应中所述使用 截断的指数退避算法重试。

聊天令牌消耗和监控

对于 Ask Advisor chat 请求，令牌表示模型计算、推理和底层数据 检索费用。聊天令牌消耗受以下因素的影响：

• 查询和分析范围 ：请求的分析的复杂性和广度。
• 模型输入和输出令牌 ：处理的上下文数据量和生成的响应叙述。
• 思考 Token ：模型综合发现结果所需的推理步骤。
• 执行延迟时间 ：多步数据探索所需的处理时间。

如需监控聊天令牌使用情况，请在 "returnPropertyQuota": true 您的 ChatRequest 中设置。响应将包含 PropertyChatQuota 对象，其中包含 tokensPerDay 和 tokensPerHour 字段，以及已消耗和剩余的余额。