Data API 限制和配額

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

配額套用方式

所有對 Google Analytics Data API 第 1 版提出的要求，都必須使用 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 配額。對 Funnel 方法發出的 API 要求會耗用 Funnel 配額。向 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 資源配額中的配額。系統會同時從 tokensPerDay、tokensPerHour 和 tokensPerProjectPerHour 扣除單一 API 要求的權杖費用。如果任何配額儲存區的剩餘配額達到 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 欄位，以及已用和剩餘餘額。