Data API 限制和配額

Data API 適用下列限制和配額。

配額套用方式

所有向 Google Analytics Data API v1 提出的要求，都必須有 Google Cloud 專案，且須遵守本頁所述的配額限制。無論使用何種方法識別呼叫專案，都會消耗配額，包括：

• 使用 OAuth 2.0 憑證驗證的要求。
• 僅使用 API 金鑰驗證的要求。

API 金鑰用於將要求與特定 Google Cloud 雲端專案建立關聯，以便計算配額和帳單。凡是使用專案憑證或 API 金鑰發出的 API 呼叫，都會計入專案和 Google Analytics 資源的適用配額。

配額類別

Data API 有四種要求配額類別：Core、Realtime、Funnel 和 Chat。

向 Core 方法發出的 API 要求會計入 Core 配額。向 Realtime 方法發出的 API 要求會計入 Realtime 配額。向漏斗方法提出的 API 要求會計入漏斗配額。向 Chat 方法發出的 API 要求會耗用 Chat 配額。每項要求只會耗用一種配額。

Analytics 資源配額

所有要求都會耗用資源配額。

• 並行要求是以同時執行的要求數量來計算。如要減少並行要求，請等待先前的要求完成，再傳送其他要求。
• 伺服器錯誤代碼為 500 和 503。只有在要求導致伺服器錯誤時，才會計入伺服器錯誤配額。如果專案和資源組合的伺服器錯誤配額用盡，系統會封鎖專案對資源的所有要求。如需錯誤回應的完整清單，請參閱「錯誤回應」。
• 每項要求都會耗用「每項資源每小時的權杖數」和「每項專案每項資源每小時的權杖數」配額。也就是說，必須有超過 3 個專案存取某項資源，才會在「每項資源每小時的權杖數量」配額用盡前，先用完「每個專案每項資源每小時的權杖數量」配額。

每項資源每小時可提出 120 項可能超出門檻的要求。userAgeBracket、userGender、brandingInterest、audienceId 和 audienceName 維度可能會套用閾值。系統會套用閾值，避免任何人在查看報表時，推斷個別使用者的受眾特徵或興趣。

資源權杖配額

每次向 Google Analytics Data API v1 提出要求，都會耗用權杖。收費的權杖數量取決於要求的複雜程度。雖然大多數要求會收取 10 個以下的權杖，但較複雜的要求 (例如 Ask Advisor chat 查詢) 會耗用更多權杖。

影響權杖消耗量的因素

要求所需的確切權杖費用會在執行時決定，因此難以精確預先計算。費用取決於多項因素，包括要求本身和 Google Analytics 資源中的基礎資料。以下因素可能導致費用增加：

• 列數：要求更多列。
• 維度和指標數量：包含更多維度和指標。
• 篩選器複雜度：使用複雜的篩選運算式。
• 日期範圍長度：查詢較長的日期範圍。
• 資料基數：高基數維度 (有許多不重複值，例如 pagePath、自訂維度) 會大幅增加權杖費用。
• 資源事件量：如果資源的事件量較多，查詢時可能比查詢資料量較少的資源消耗更多權杖。

監控權杖用量

如要判斷特定 API 呼叫的權杖費用，最有效的方法是在要求主體中加入 "returnPropertyQuota": true 參數 (runReport、batchRunReports、runPivotReport、batchRunPivotReports、runRealtimeReport 和 runFunnelReport 支援)。API 回應會包含 PropertyQuota 物件，詳細列出該特定要求消耗的權杖和剩餘配額。

使用 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 中的每個欄位都對應至Analytics 資源配額中的配額。單一 API 要求的權杖費用會同時從 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 權杖消耗和監控

對於 Ask Advisor chat 要求，權杖代表模型運算、推論和基礎資料擷取成本。Chat 詞元用量受下列因素影響：

• 查詢和分析範圍：要求分析的複雜度和廣度。
• 模型輸入和輸出詞元：處理的脈絡資料量和生成的回覆敘述。
• 思考詞元：模型統整發現項目所需的推論步驟。
• 執行延遲時間：多步驟資料探索所需的處理時間。

如要監控對話權杖用量，請在 ChatRequest 中設定 "returnPropertyQuota": true。回應會包含 PropertyChatQuota 物件，其中包含 tokensPerDay 和 tokensPerHour 欄位，內含已用和剩餘餘額。