管理 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 的 Data API Analytics 4 資源會使用權杖儲存系統來管理 API 配額。目的地： 理解概念：假設有一個值區 符記任何 API 要求都會先檢查值區。如果沒有 就會失敗。否則，系統會執行要求 會使用值區中的一或多個符記 要求。系統會將值區中的權杖回收至已達數量上限 間隔。

視您使用 Data API 方法而定，系統提供三種不同的配額 類別：

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

此外，Data API 方法也會檢查多個值區 配額權杖：

1. 每日每項資源
2. 每小時每項資源
3. 每項資源每小時每項資源
4. 每資源並行要求數
5. 每項專案每小時每項資源的伺服器錯誤

每當收到 Data API 要求時，系統就會檢查這五個值區。 資源。如果「任何」值區為空白，要求會立即失敗 429 錯誤。如果所有值區均非空白，則在單一值區 系統會從每個屬性並行要求值區取用權杖， 系統會執行 API 要求視要求的複雜度而定 前三個值區分別都會使用一定數量的權杖 待執行完畢。「每個資源同時發出的要求數」也會 才能取得補回符記

每小時每項專案配額可確保用盡 一或多位使用者不會影響應用程式的其他使用者。在這裡，project 指的是應用程式的 GCP 專案。「每小時每資源」配額為 通常是每小時每項資源每項專案配額的四倍。到此結束 資源前至少有四項不同的專案 您可以達到每小時每資源配額。同時在兩個位置強制執行配額 專案和屬性層級確保配額問題僅限於單一 而且不會影響應用程式正在存取的其他資源。

警告： 我們強烈建議開發人員不要將配額符記分割到 多項 API 專案此舉違反了《Google API 服務條款》。

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

所有配額權杖都會按照指定的時間間隔，達到上限。詳情請參閱 Google Analytics Data API 配額：瞭解更新的配額資訊。例如： Core 方法在每項資源每小時每個資源中可獲得 1,250 個配額權杖 Cloud Storage 也提供目錄同步處理功能 方便您同步處理 VM 目錄與值區假設應用程式的平均要求會耗用 10 個配額 因此您的應用程式每小時可以發出 125 個核心要求， 標準資源，以及為任何 Analytics 資源數量 (1250 個「核心」要求) 的 10 倍。 360 資源。配額較高的權杖上限是 Analytics 360 資源的優點

前三個值區的權杖用量取決於 則在要求前，要先預測確切權杖使用情形 下列何者通常會提高要求的複雜度， 產生的權杖使用時間：

• 要求更多維度
• 查詢時間範圍較長
• 納入基數較高的維度
• 查詢事件計數較多的屬性

因此，對兩個不同屬性的相同查詢可能會產生 因為維度的基數 流量變化，或流量可能有所不同。不過， 流量層級和設定類似的資源 產生類似權杖的使用情形您可以使用這項假設來預測客戶權杖的使用情形 也會採取相關行動

注意： 如果您先前已為通用 Analytics 使用 Reporting API， 您會發現 Reporting API 已強制執行應用程式/API 專案的配額 第二，自訂角色只能 套用至專案或機構但對於 Data API，違規處置是由 Google Analytics 資源進行 以及 API 專案層級。

監控配額用量

如要監控配額用量並向使用者傳達相關資訊，您可以新增 "returnPropertyQuota": true 到 API 要求主體。這樣將會傳回 PropertyQuota 物件和 API 回應。PropertyQuota 物件 會包含所有五項 Cloud Storage 也提供目錄同步處理功能 方便您同步處理 VM 目錄與值區以下是要求主體和回應的範例：

要求

{
  "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 要求後，您將會看到 配額，以及該要求的配額。是 透過應用程式將這些資訊提供給使用者 存取 API

注意： 在目前的 Data API 階段，您必須成功執行 取得 API 要求，用來取得 PropertyQuota 物件。如果資源已經 配額權杖值區已用盡，您的要求將會失敗，並顯示 429 錯誤和 回應將不會包含 PropertyQuota 物件。如果您受到 會希望應用程式另外能藉由 存取配額資訊，+1 這項功能要求。

配額管理

建議您實作配額管理的最佳做法，以便達成以下目的： 充分運用 Data API。其他 將資源升級至 360 可提高 透過 API 存取的資料

最佳做法

您可以透過大致兩種方式降低應用程式的配額用量：

• 傳送的 API 要求數量較少
• 傳送較不複雜的 API 要求

請將這兩個原則謹記在心，您可以採行以下做法：

• 快取：導入快取層將同時改善可用性。 管理應用程式的配額Google Analytics 本身就會快取 傳送您的 API 要求，但重複的要求仍會產生配額權杖。變更者： 快取 API 回應，就能大幅減少重複執行的次數 要求。舉例來說，標準資源的當日資料可有 4 個 或是快取到期時間更長的時間請參閱「Google 的資料更新間隔」 分析。
• 合併要求：嘗試將多個 API 要求合併為單一要求。 舉例來說，假設在 2 天內提出 5 次資料要求，可能會使用 3 次 配額權杖相較於 10 天內 1 個要求。如果 如果多個請求只因一個維度而改變，請考慮合併 合併為單一請求
• 簡化要求：將要求的資料量限制在最少的資料量 應用程式與使用者的需求擁有大量的資料列/資料欄，或 複雜的篩選條件會耗用更多配額權杖。較長的日期範圍 費用通常較高 (例如，將日期範圍從 28 天變更為 365 天) 天可以使用配額權杖的 3 倍)。您也可以考慮使用 請盡量使用基數較低的維度 (例如要求 dateHour) 而不是 dateHourMinute)。
• 有效使用 limit：變更 API 中的 limit 減少傳回的資料列數量並未顯著影響 配額權杖。舉例來說，以 1 萬列為上限的 5 個要求， 則會耗用五倍配額權杖 (有 1 個要求，上限為 5 萬個)。
• 使用正確的方法類別：如上所述，配額限制為 分別在三種方法類別中請採用適當的方法 用途可以節省其他類別的配額。舉例來說 在應用程式中利用 Core 方法的資料建立專屬漏斗 使用 runFunnelReport 方法建立漏斗。
• 更新預設設定：撰寫或自訂報表時 使用者可能不會更新 且只在執行階段變更。如果應用程式 預設日期範圍是 365 天，使用者通常會查看 28 天的報表 導致使用超出標準的配額 可以限制預設設定中的範圍和選項 使用者會針對自己的用途選取最合適的設定。在某些情況下 也可以限制使用者可變更的預設值。
• 將要求排入佇列和延遲載入：請留意並行載入 每個資源的要求符記限制。應用程式不得發送 同時提出的要求數量過多如果您的應用程式含有大量 導致大量 API 要求的 UI 元素 使用指數處理 UI、延遲載入，以及將要求排入佇列 重試。使用 returnPropertyQuota 方法積極 監控應用程式的每個資源並行要求權杖使用狀況。

管理使用者體驗和期望

• 在使用者執行查詢前，先提供意見回饋，以免權杖用量偏高。 舉例來說，包含多項高基數維度的查詢、 因此可能會使用大量符記提供警示和 進行這類查詢的確認提示 並降低報表範圍 舉個簡單的例子，您可以定義情境 並指示 AI 如何回應服務中心查詢
• 如果是自訂報表解決方案，則需提供瞭解機制 查詢報表中每個元素的使用情況。舉例來說，您可以提供 偵錯檢視畫面，會列出每個報表元素的配額權杖使用情形。
• 針對特定配額錯誤類型提供意見回饋，並引導使用者 動作。
• Google Analytics 360 資源的配額上限是該資源的 5 至 10 倍 標準資源上，透過 Google Analytics 360 使用上變得更加靈活 資源

超過預設上限的 API 配額不適用於 Data API： Google Analytics 4。Google Analytics 360 為 Google Analytics 360 提供的配額上限 Google Analytics 4 資源。如果使用者即將達到配額上限 採用最佳做法後，他們應考慮將 將資源套用至 360使用者還可以選擇使用 Google Analytics BigQuery Export這樣一來，使用者就能匯出事件層級資料 並執行自己的分析。

如對 Data API 配額有其他疑問，請前往 GA Discord 或 在 Stack Overflow 上提問。如果您對「Google 資料」平台提出特定功能要求 API，您可以透過 Issue Tracker 發布。