管理 Google Analytics Data API 的配額

Google Analytics 開發人員服務代表 Minhaz Kazi – 2023 年 2 月

如果您使用 [Google Analytics Data API] 開發應用程式，請務必瞭解 API 的配額和限制。如果應用程式設計完善，使用者較不容易達到配額上限。部分相關最佳做法也能協助您對 API 執行高效查詢。這有助於加快應用程式中的報表和資訊主頁，並提供更理想的使用者體驗。本文將說明配額制度，以及實作 Google Analytics Data API 的最佳做法。

瞭解 Google Analytics Data API 的配額系統

由於數百萬名開發人員和使用者都會使用 Google Analytics，因此 API 請求配額可避免系統處理超出負荷的資料量，同時確保系統資源能公平分配。Google Analytics 4 資源的 Data API 會使用權杖 bucket 系統管理 API 配額。如要瞭解這個概念，請想像有一個水桶，最多可裝入一定數量的權杖。所有 API 要求都會先檢查 bucket。如果沒有剩餘權杖，要求就會失敗。否則，系統會執行要求，並視要求複雜度從 bucket 中取用一或多個符記。權杖會在固定時間間隔內補充至 bucket，達到上限。

視您使用的 Data API 方法而定，配額類別分為三種：

即時 (適用於 runRealtimeReport)
漏斗 (適用於「runFunnelReport」)
核心 (適用於所有其他方法)

此外，Data API 方法會檢查多個配額權杖儲存區：[Google Analytics Data API 配額]。

每項資源每天
每項資源每小時
每項專案每項資源每小時
每個資源的並行要求數
每項專案每項資源每小時的伺服器錯誤數

只要有資源的 Data API 要求傳入，系統就會檢查這五個值區。如果任何 bucket 為空，要求會立即失敗並出現 429 錯誤。如果所有 bucket 都不是空的，系統會從「每個資源的並行要求」bucket 中取用單一權杖，然後執行 API 要求。根據要求的複雜度，執行完成後，系統會從前三個儲存區各消耗一定數量的權杖。系統也會在這個時間點補充「每個資源的並行要求」權杖。

每項資源每小時的配額可確保一或多位使用者的配額用盡時，不會影響應用程式的其他使用者。這裡的「project」是指應用程式的 GCP 專案。「每項資源每小時」配額通常是「每項專案每項資源每小時」配額的四倍。因此，使用者必須透過至少四個不同的專案存取資源，才能用盡「每小時每個資源」配額。在專案和資源層級強制執行配額，可確保配額問題僅限於單一資源，不會影響應用程式存取的其他資源。

「伺服器錯誤」配額是指含有 500 或 503 代碼的 API 回應。如果應用程式在存取資源時產生過多錯誤，就會耗盡「每小時每個資源每個專案的伺服器錯誤」配額。

所有配額權杖都會在指定間隔內補充至上限。如需最新配額資訊，請參閱「[Google Analytics Data API 配額]」。舉例來說，核心方法在「每項資源每小時每個專案」儲存區中，可取得 1,250 個配額權杖。假設應用程式的平均要求會消耗 10 個配額權杖，則應用程式每小時可對標準資源提出 125 個 Core 要求，對任何 Analytics 360 資源則可提出 10 倍的 Core 要求 (1250 個 Core 要求)。配額權杖上限較高是 Analytics 360 資源的主要優點之一。

由於前三個 bucket 的權杖消耗量取決於要求的複雜度，因此在執行要求前，很難預測確切的權杖用量。下列情況通常會增加要求複雜度，因此會導致詞元用量增加：

要求更多維度
查詢較長的日期範圍
包括基數較高的維度
查詢事件數較高的資源

因此，兩個不同資源的相同查詢可能會導致完全不同的權杖用量，因為維度的基數可能不同，或流量可能不同。不過，如果資源的流量和設定相似，預期權杖用量也會差不多。您可以在規劃和應用程式設計階段，使用這項假設預測顧客的權杖用量。

監控配額用量

如要監控配額用量並將該資訊傳達給使用者，您可以在 API 要求主體中加入 "returnPropertyQuota": true。這會傳回 PropertyQuota 物件和 API 回應。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 要求合併為單一要求。舉例來說，在 2 天的時間範圍內提出 5 個資料要求，與在 10 天的時間範圍內提出 1 個要求相比，前者可能需要 3 倍的配額權杖。如果有多項要求，但只有一個維度不同，建議將這些要求合併為一項。
簡化要求：將要求限制在應用程式和使用者所需的最低資料量。大量資料列/資料欄或複雜的篩選條件會耗用更多配額權杖。較長的日期範圍通常較為昂貴 (例如將日期範圍從 28 天變更為 365 天，可能會消耗 3 倍的配額權杖)。此外，請盡可能使用基數較低的維度 (例如要求 dateHour，而非 dateHourMinute)。
有效使用 limit：在 API 要求中變更 limit，減少傳回的資料列數量，不會大幅影響配額權杖用量。舉例來說，如果 5 個要求都設有 1 萬列的限制，與 1 個設有 5 萬列限制的要求相比，前者會消耗五倍的配額權杖。
使用正確的方法類別：如上所述，配額限制會分散在三種方法類別中。針對適當的用途使用正確方法，可節省其他類別的配額。舉例來說，您不必使用 Core 方法中的資料，在應用程式中建立自己的漏斗，只要使用 runFunnelReport 方法即可建立漏斗。
更新預設設定：在平台上製作或自訂報表時，使用者可能不會更新應用程式顯示的預設選項，只會在執行階段變更這些選項。如果應用程式的預設日期範圍為 365 天，而使用者通常查看 28 天的報表，這會導致應用程式定期耗用超出需求的配額。建議您在預設設定中限制範圍和選項，讓使用者根據自己的用途選取最佳設定。或者，在某些情況下，您也可以限制使用者可變更的預設設定。
將要求加入佇列及延遲載入：請注意「每個資源的並行要求」權杖限制。應用程式不應同時傳送過多要求。如果應用程式有大量 UI 元素，導致 API 要求數量龐大，請考慮將 UI 分頁、延遲載入，並使用指數輪詢將要求排入佇列，以便重試。使用 returnPropertyQuota 方法，積極監控應用程式的每個資源的並行要求權杖用量。

管理使用者體驗和期望

在使用者執行可能耗用大量權杖的查詢前，提供意見回饋。舉例來說，如果查詢包含多個高基數維度或時間範圍較長，可能會使用大量權杖。針對這類查詢提供警告和確認提示，可避免使用者對報表進行不必要的變更，並協助他們將查詢範圍限制在所需範圍內。
如果是自訂報表解決方案，請提供使用者瞭解報表中各個元素查詢用量的方式。舉例來說，您可以提供偵錯檢視畫面，列出每個報表元素的配額權杖用量。
針對特定配額錯誤類型提供意見回饋，並建議使用者採取行動。
Google Analytics 360 資源的配額上限是標準資源的 5 到 10 倍，因此使用 Google Analytics 360 資源時，您能享有更大的彈性。

Google Analytics 4 的 Data API 配額無法超過預設上限。Google Analytics 360 為 Google Analytics 4 資源提供較高的配額上限。如果使用者在採用最佳做法後，仍達到配額上限，建議將資源升級至 360。使用者也可以選擇使用 Google Analytics BigQuery Export。使用者可將事件層級資料匯出至 BigQuery，並自行進行分析。

如對 Data API 配額有其他疑問，請前往 GA Discord 或在 Stack Overflow 上提問。如果您對 Data API 有任何特定功能要求，請透過 Issue Tracker 提出。