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 请求会消耗核心配额。对 Realtime 方法的 API 请求会消耗 Realtime 配额。对漏斗方法的 API 请求会消耗漏斗配额。向 Chat 方法发出的 API 请求会消耗 Chat 配额。每个请求仅消耗一种配额。

配额类别 API 方法
核心 runReport、runPivotReport、batchRunReports、batchRunPivotReports、runAccessReport、getMetadata、checkCompatibility、createAudienceExports
实时 runRealtimeReport
漏斗图 runFunnelReport
聊天 properties.chat

Google Analytics 媒体资源配额

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

配额名称 标准版媒体资源数量上限 Analytics 360 版媒体资源数量上限
每项媒体资源每天的核心令牌数 200000 200 万
每项媒体资源每小时的核心令牌数 40000 400000
每个项目每项媒体资源每小时的核心令牌数 14,000 140,000
每项媒体资源的核心并发请求数 10 50
每个项目每项媒体资源每小时的核心服务器错误数 10 50
每项媒体资源每天的实时令牌数 200000 200 万
每项媒体资源每小时的实时令牌数 40000 400000
每个项目每项媒体资源每小时的实时令牌数 14,000 140,000
每项媒体资源的实时并发请求数 10 50
每个项目每项媒体资源每小时的实时服务器错误数 10 50
每项媒体资源每天的漏斗令牌数 200000 200 万
每项媒体资源每小时的漏斗令牌数 40000 400000
每个项目每项媒体资源每小时的漏斗令牌数 14,000 140,000
每项媒体资源的漏斗并发请求数 10 50
每个项目每项媒体资源每小时的漏斗服务器错误数 10 50
每项媒体资源每天的聊天配额 3,750,000 3,750,000
每项媒体资源每小时的聊天 token 数 50 万 50 万
  • 并发请求数通过同时执行的请求数来衡量。如需降低请求并发，请等待之前的请求完成，然后再发送其他请求。
  • 服务器错误代码为 500 和 503。只有当请求导致服务器错误时，系统才会扣减服务器错误配额。当某个项目和媒体资源对的“服务器错误”配额耗尽时，系统会阻止该项目向该媒体资源发出的所有请求。如需查看错误响应的完整列表，请参阅错误响应。
  • 每个请求都会消耗“每项媒体资源每小时令牌数”和“每个项目每项媒体资源每小时令牌数”的配额。这意味着，必须有超过 3 个项目访问同一项媒体资源，才可能在“每个项目每项媒体资源每小时的令牌数”配额用尽之前，先用尽“每项媒体资源每小时的令牌数”配额。

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

媒体资源令牌配额

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

影响 token 消耗量的因素

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

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

监控 token 使用情况

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

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 后，响应会包含一个 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 请求的 token 费用会同时从 tokensPerDay、tokensPerHour 和 tokensPerProjectPerHour 中扣除。如果任何配额桶剩余 0，则对该媒体资源的后续请求会返回 429 RESOURCE_EXHAUSTED 错误。

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

Chat token 消耗和监控

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

  • 查询和分析范围：所请求分析的复杂性和广度。
  • 模型输入和输出 token：处理的情境数据量和生成的回答叙述。
  • 思考 Token：整合发现结果所需的模型推理步骤。
  • 执行延迟时间：多步数据探索所需的处理时间。

如需监控聊天 token 用量，请在 ChatRequest 中设置 "returnPropertyQuota": true。响应将包含 PropertyChatQuota 对象，其中包含 tokensPerDay 和 tokensPerHour 字段，分别表示已用余额和剩余余额。