管理 Google Analytics（分析）Data API 的配额

Minhaz Kazi，Google Analytics 开发技术推广工程师 - 2023 年 2 月

如果您使用 Google Analytics Data API 开发应用，则应了解该 API 的配额和限制的工作原理。如果您的应用设计得当，用户不太可能会达到配额限制。此外，采取一些相关的最佳做法后，还可以实现高效的 API 查询。这可以加快您应用中报告和信息中心的生成速度，为用户提供更加理想的体验。本文介绍了配额系统以及实现 Google Analytics Data API 的最佳做法。

了解 Google Analytics Data API 的配额系统

由于有数百万开发者和用户在使用 Google Analytics，因此为 API 请求分配配额可以防止系统处理的数据量超出其处理能力，同时又能确保公平分配系统资源。适用于 Google Analytics 4 媒体资源的 Data API 使用令牌桶系统来管理 API 配额。为了便于理解这个概念，请假设您有一个桶，最多可以容纳最大数量的令牌。任何 API 请求都会先检查该令牌桶。如果没有剩余的令牌，请求将会失败。如果有剩余的令牌，系统则会执行相应请求。根据请求的复杂程度，此过程将消耗令牌桶中的一个或多个令牌。系统会按照固定的时间间隔补充令牌桶中的令牌，使其达到数量上限。

根据您所使用的 Data API 方法，共有三个不同的配额类别：

Data API 方法将检查多个令牌桶中的配额令牌：

  1. 每项媒体资源每天
  2. 每项媒体资源每小时
  3. 每个项目每项媒体资源每小时
  4. 每项媒体资源的并发请求数
  5. 每个项目每项媒体资源每小时的服务器错误数

每当收到针对媒体资源的 Data API 请求时，系统就会检查这五个令牌桶。如果有任何令牌桶为空，相应请求将立即失败，并返回 429 错误。如果所有令牌桶都不空，系统将会使用“每项媒体资源的并发请求数”令牌桶中的一个令牌，然后执行该 API 请求。根据请求的复杂程度，请求执行完毕后，前三个令牌桶的每一个中都会消耗一定数量的令牌。此时，系统还会向“每项媒体资源的并发请求数”令牌桶中补充一个令牌。

“每个项目每项媒体资源每小时”配额可确保一位或多位用户的配额消耗不会影响应用的其他用户。这里所说的“项目”是指您应用的 Google Cloud Platform (GCP) 项目。“每项媒体资源每小时”配额通常是“每个项目每项媒体资源每小时”配额的 4 倍。因此，对于最终用户来说，每项媒体资源必须至少被 4 个不同的项目访问，“每项媒体资源每小时”配额才会耗尽。同时在项目一级和媒体资源一级强制执行配额，可确保配额问题只会在单个媒体资源中出现，而不会影响应用所访问的其他媒体资源。

“服务器错误数”配额是指包含 500 或 503 代码的 API 响应。如果您的应用在访问媒体资源时生成的错误过多，则会导致“每个项目每项媒体资源每小时的服务器错误数”配额耗尽。

所有配额令牌均会按照规定的时间间隔补充至配额限制的数量。如需了解更新后的配额信息，请参阅 Google Analytics Data API 配额。例如，核心方法可从“每个项目每项媒体资源每小时”令牌桶中获取 1,250 个配额令牌。假设应用发送的每个请求平均会消耗 10 个配额令牌，那么应用每小时可针对标准媒体资源发出 125 个核心请求，针对任何 Google Analytics 360 媒体资源发出的核心请求数量将会是前者的 10 倍（即 1,250 个核心请求）。配额令牌限制更高是 Google Analytics 360 媒体资源的主要优势之一。

由于前三个令牌桶的令牌消耗数量取决于请求的复杂性，因此在请求执行之前很难预测确切的令牌用量。以下情况通常会增加请求的复杂性，从而导致消耗更多令牌：

  • 请求更多维度
  • 查询更长的时间范围
  • 包含基数更高的维度
  • 查询事件数更多的媒体资源

因此，如果针对两个不同的媒体资源执行相同的查询，令牌用量可能完全不同，因为维度的基数可能会有差异，或者流量可能会不同。不过，如果媒体资源的级别流量和配置均类似，其令牌用量也会相差不大。在规划和应用设计阶段，您可以利用此假设来预测客户令牌用量。

监控配额使用情况

如需监控配额使用情况并将相关信息传达给最终用户，可以将 "returnPropertyQuota": true 添加到 API 请求正文。这样一来，系统在返回 API 响应时还会一并返回 PropertyQuota 对象。PropertyQuota 对象将包含全部五个令牌桶中的消耗量和剩余配额状态。下面是请求正文和响应示例：

请求

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

响应

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

因此，每次成功执行 Data API 请求之后，您应该都可以看到相应请求消耗了多少配额以及相应媒体资源剩余的配额。您还可以通过应用界面向用户显示这些信息。

配额管理

我们建议实施下文中详述的配额管理最佳做法，以便充分利用 Data API。此外，将媒体资源升级到 360 版可增加通过该 API 访问的数据量。

最佳做法

减少应用配额用量的方法大致有两种：

  • 减少所发送 API 请求的数量
  • 降低所发送 API 请求的复杂性

根据这两个原则，您可以采取以下做法：

  • 缓存：实现缓存层既有利于提升应用易用性，还能改善配额管理。Google Analytics 本身会缓存您的 API 请求，但重复的请求仍会消耗配额令牌。通过缓存 API 响应，您可以大幅减少重复的请求数量。例如，标准媒体资源日内数据的缓存到期时间可以长达 4 小时或更长。请参阅 Google Analytics 的数据新鲜度。
  • 合并请求：尝试将多个 API 请求合并为一个请求。例如，与 1 个针对 10 天内数据的请求相比，5 个针对 2 天内数据的请求会消耗 3 倍的配额令牌。如果您有多个请求，而它们之间只存在单个维度的差别，请考虑将这些请求合并为单个请求。
  • 简化请求：将您的请求限制为应用和用户所需的最少数据量。大量的行/列或复杂的过滤条件将消耗更多的配额令牌。日期范围越长，费用通常也会更高（例如，将日期范围从 28 天更改为 365 天后，消耗的配额令牌数量将会是原来的 3 倍）。此外，您还可以考虑尽可能使用基数更低的维度（例如，请求 dateHour，而不是 dateHourMinute）。
  • 有效使用 limit：更改 API 请求中的 limit 以减少返回的行数，并不会对消耗的配额令牌数量产生重大影响。例如，与 1 个上限为 5 万行的请求相比，5 个上限为 1 万行的请求会消耗 5 倍的配额令牌。
  • 使用合适的方法类别：如前所述，配额限制分为三种方法类别。针对合适的使用情形使用合适的方法可以节省其他类别的配额。例如，不要使用核心方法提供的数据在应用中创建自己的漏斗，而应使用 runFunnelReport 方法来创建漏斗。
  • 更新默认设置：在平台上编写或自定义报告时，用户可能不会更新应用显示的默认选项，而只会在运行时进行更改。如果应用的默认日期范围为 365 天，而用户通常查看的是 28 天报告，那么最终消耗的配额就会超过常规需求。请考虑限制默认设置中的范围和选择，允许用户针对其使用情形选择最佳设置。或者，在某些情况下，您还可以限制用户可以更改的默认值。
  • 建立请求队列并延迟加载：请注意“每项媒体资源的并发请求数”令牌限制。您的应用不应同时发出过多请求。如果应用具有大量界面元素，导致发出大量 API 请求，请考虑对界面进行分页、延迟加载，以及使用指数退避算法建立请求队列，以便进行重试。使用 returnPropertyQuota 方法主动监控应用的“每项媒体资源的并发请求数”令牌用量。

管理用户体验和预期

  • 在用户运行令牌用量可能较高的查询之前，应向其反馈此信息。例如，具有多个高基数维度或较长时间范围的查询可能会消耗大量令牌。针对此类查询提供警告和确认提示可以防止用户对报告进行不必要的更改，并帮助他们限制查询的范围。
  • 对于自定义报告解决方案，应为用户提供一种方法，帮助他们了解其报告中每个元素的查询用量。例如，您可以提供一个调试视图，在其中列出每个报告元素的配额令牌用量。
  • 针对特定类型的配额错误提供反馈，并说明用户应执行的操作。
  • 由于 Google Analytics 360 媒体资源的配额限制是标准媒体资源的 5-10 倍，因此您可以更加灵活地使用 Google Analytics 360 媒体资源。

适用于 Google Analytics 4 的 Data API 不支持将 API 配额提高至默认限制以上。Google Analytics 360 为 Google Analytics 4 媒体资源提供了更高的配额限制。在实施最佳做法后，如果用户仍达到了配额限制，则他们应考虑将媒体资源升级为 360 版。用户可以选择的另一种方法是使用 Google Analytics BigQuery Export。借助该功能，用户可以将事件级数据导出到 BigQuery 并运行自己的分析。

如果您对 Data API 配额有其他疑问，请访问 GA Discord 或在 Stack Overflow 上提问。如需提出关于 Data API 的特定功能请求，可以在我们的问题跟踪器上发布。