本頁面由 Cloud Translation API 翻譯而成。

管理 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 使用權杖值區系統來管理 API 配額。如要瞭解這個概念：假設某個值區可容納的符記數量上限，任何 API 要求都會先檢查值區。如果沒有剩餘的符記，要求就會失敗。否則，系統會執行要求，並根據要求的複雜度，從值區取用一或多個符記。系統會在固定的時間間隔內，將權杖補充至值區中的上限。

視您使用的資料 API 方法而定，配額類別有三種：

即時 (runRealtimeReport)
漏斗 (runFunnelReport)
核心 (所有其他方法)

而 Data API 方法會檢查多個值區，確認是否包含配額權杖：

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

每當系統收到 Data API 要求時，就會檢查這五個值區。如果任何值區為空白，要求會立即失敗，並顯示 429 錯誤。如果所有值區都並非空白，系統會從「每個屬性的並行要求」值區取用單一憑證，然後執行 API 要求。根據要求的複雜程度，執行作業完成後，系統會從前三個值區中使用指定數量的符記。目前，每個資源的並行要求也會取得補充權杖。

「每個資源每小時每項資源每小時每項專案」配額可確保系統為一或多位使用者補充配額，不會影響應用程式的其他使用者。該專案指的是應用程式的 GCP 專案。「每小時每個資源」配額通常是「每小時每項資源每小時每項資源」配額的四倍。因此，使用者至少須有四個不同專案存取資源，每小時每資源配額才能用完。同時在專案和屬性層級強制執行配額，可確保配額問題僅限於單一屬性，不會影響應用程式存取的其他屬性。

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

所有配額權杖都會以規定的間隔充實。如需最新的配額資訊，請參閱 Google Analytics Data API 配額。舉例來說，Core 方法會在「每個資源每小時每項資源」值區中取得 1,250 個配額權杖。假設應用程式平均要求耗用了 10 個配額憑證，您的應用程式將能對標準資源每小時提出 125 個核心要求，以及 10 倍 (1250 個核心要求) 供任何 Analytics (分析) 360 資源使用。提高配額權杖上限是 Analytics (分析) 360 資源的主要優點之一。

前三個值區的權杖用量取決於要求的複雜度，因此在要求執行前很難預測確切的權杖使用情形。一般來說，下列項目會增加要求的複雜度，進而導致權杖使用：

正在要求更多維度
正在查詢較高的時間範圍
納入基數較高的維度
查詢事件計數較高的資源

因此，如果對兩個不同的屬性執行相同查詢，可能會導致符記用量完全不同，因為維度的基數可能各不相同，或者流量的數量不同。不過，您可以預期流量層級類似及設定類似的屬性具有類似的符記用法。您可以運用這項假設，在規劃和應用程式設計階段預測客戶權杖的使用情形。

監控配額用量

如要監控配額用量，並將該資訊傳送給使用者，您可以在 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 項要求，您可以將配額權杖使用 3 倍，而在 10 天的時間範圍內 1 個要求則可以使用 3 倍。如果您有多個要求，而且只有單一維度不同，請考慮將這些要求合併為單一要求。
簡化要求：將您的要求限制為應用程式和使用者所需的最低資料量。大量的資料列/資料欄或複雜的篩選條件會耗用更多配額權杖。較長的日期範圍通常費用較高 (例如，將日期範圍從 28 天變更為 365 天，可能會耗用配額權杖的 3 倍)。此外，您也可以盡量使用基數較低的維度 (例如要求 dateHour 而非 dateHourMinute)。
limit 有效用量：變更 API 要求中的 limit，以減少傳回的資料列數量，不會對耗用的配額權杖造成顯著影響。舉例來說，假設 1 項要求的上限是 1 萬個，比起 1 個限制為 5 萬個要求，5 次要求的配額權杖可能會耗用五次。
使用正確的方法類別：如前所述，配額限制適用三種方法類別。若能搭配適當的用途，就能節省其他類別的配額。舉例來說，與其使用 Core 方法的資料自行建立漏斗，不如使用 runFunnelReport 方法建立漏斗。
更新預設設定：在平台上編寫或自訂報表時，使用者可能不會更新應用程式顯示的預設選項，而只會在執行階段進行變更。如果您的應用程式的預設日期範圍是 365 天，且使用者通常會查看 28 天的報表，那麼最終耗用的配額會多於正常的配額。請考慮在預設設定中限制範圍和選項，並讓使用者根據用途選取最合適的設定。或者，在某些情況下，您也可以限制使用者能夠變更的預設條件。
將要求和延遲載入排入佇列：請留意「每個資源的並行要求」權杖限制。您的應用程式不應同時傳送過多要求。如果應用程式含有大量 UI 元素，並產生大量 API 要求，請考慮將 UI 分頁、延遲載入以及將要求排入佇列，以便重試。請使用 returnPropertyQuota 方法，主動監控應用程式的每個屬性並行要求權杖使用情況。

控管使用者體驗和期望

在使用者執行具有高權杖用量的查詢前，先提供意見回饋。舉例來說，如果查詢包含多個高基數維度或時間範圍較大，就可能使用大量符記。針對這類查詢提供警告和確認提示，可以防止使用者對報表進行不必要的變更，並協助他們將查詢的範圍限制在查詢範圍內。
針對自訂報表解決方案，可讓使用者瞭解報表中各項元素的查詢使用情形。舉例來說，您可以提供偵錯檢視畫面，列出每個報表元素的配額權杖用量。
請針對特定類型的配額錯誤類型提供意見回饋，並提出使用者動作建議。
相較於標準資源，Google Analytics (分析) 360 資源的配額限制為標準資源的 5 至 10 倍，因此您能運用更多 Google Analytics (分析) 360 資源彈性。

超過預設上限的 API 配額不適用於 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。