標準錯誤回應
如果 Real Time Reporting API 要求成功，API 就會傳回 200 狀態碼。如果要求發生錯誤，API 會根據錯誤類型在回應中傳回 HTTP 狀態碼、狀態和原因。此外，回應主體會詳細說明導致錯誤的原因。以下為錯誤回應的示例：
{
"error": {
"errors": [
{
"domain": "global",
"reason": "invalidParameter",
"message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]",
"locationType": "parameter",
"location": "max-results"
}
],
"code": 400,
"message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]"
}
}
錯誤表
| 程式碼 | 原因 | 說明 | 建議做法 |
|---|---|---|---|
| 400 | invalidParameter |
表示要求參數有一個無效值。錯誤回應中的 locationType 和 location 欄位會提供無效值的相關資訊。 |
未修正問題前請勿重試。您必須為錯誤回應中指定的參數提供有效的值。 |
| 400 | badRequest |
表示查詢無效。例如：缺少父項 ID，或要求的維度或指標組合無效。 | 未修正問題前請勿重試。您必須變更 API 查詢，查詢才會生效。 |
| 401 | invalidCredentials |
表示驗證權杖無效或已過期。 | 未修正問題前請勿重試。您必須取得新的驗證權杖。 |
| 403 | insufficientPermissions |
表示使用者對查詢中指定的實體的權限不足。 | 未修正問題前請勿重試。您必須取得足夠的權限，才能對指定實體執行作業。 |
| 403 | dailyLimitExceeded |
表示使用者已超出每日配額 (每個專案或每個資料檢視 (設定檔))。 | 未修正問題前請勿重試。你已用完每日配額。請參閱 API 限制和配額。 |
| 403 | userRateLimitExceeded |
表示已超過每位使用者每 100 秒的查詢數上限。Google API 控制台中的預設值是每位使用者每 100 秒 100 次查詢，您可以在 Google API 控制台中提高上限至 1,000 個。 | 使用指數輪詢重試。請降低傳送要求的速率。 |
| 403 | rateLimitExceeded |
表示專案每 100 秒查詢次數的頻率已超過上限。 | 使用指數輪詢重試。請降低傳送要求的速率。 |
| 403 | quotaExceeded |
表示 Core Reporting API 中每個資料檢視 (設定檔) 的並行要求數量已達 10 個。 | 使用指數輪詢重試。您需等待至少一個處理中的要求 (設定檔) 才能完成。 |
| 500 | internalServerError |
發生非預期的內部伺服器錯誤。 | 這項查詢最多只能重試一次。 |
| 503 | backendError |
伺服器傳回錯誤。 | 這項查詢最多只能重試一次。 |
處理 500 或 503 回應
500 或 503 錯誤可能會在負載量較大時，或針對較大型的要求提出。若是較大型的要求，建議您縮短資料要求的時間範圍。此外，您也可以實作指數輪詢。這些錯誤出現的頻率取決於資料檢視 (設定檔) 以及與該資料檢視相關的報表資料數量。如果查詢會導致單一資料檢視 (設定檔) 發生 500 或 503 錯誤，不一定會對具有不同資料檢視 (設定檔) 的相同查詢造成錯誤。
實行指數輪詢
指數輪詢是指用戶端定期重試失敗要求的程序，且要求數量會隨時間增加。這是網路應用程式的標準錯誤處理策略。Real Time Reporting API 的設計宗旨是讓用戶端選擇重試失敗的要求時，會使用指數輪詢策略。使用指數輪詢不但可「必要」，還能提高頻寬用量、減少取得成功回應所需的要求數，並盡可能提高並行環境中的要求總處理量。
實作簡單指數輪詢的流程如下。
- 向 API 提出要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 1 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 2 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 4 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 8 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 16 秒 +
random_number_milliseconds秒 - 重試要求
- 如果持續發生錯誤，請停止並記錄錯誤。
在上述流程中，random_number_milliseconds 是小於或等於 1000 的隨機毫秒數。這是為了避免某些並行實作時發生特定鎖定錯誤。每次等待之後，都必須重新定義 random_number_milliseconds。
注意：等待時間一律是 (2 ^ n) + random_number_milliseconds，其中 n 是最初定義為 0 的單調遞增整數。對於每次疊代 (每個要求)，n 會遞增 1。
演算法已設定為會在 n 等於 5 時終止。此上限的用意只是防止用戶端無限重試，導致要求在總延遲時間達到約 32 秒之後，才會被視為「無法復原的錯誤」。
下列 Python 程式碼是上述流程的實作，用於從名為 makeRequest 的方法中發生的錯誤復原。
import random
import time
from apiclient.errors import HttpError
def makeRequestWithExponentialBackoff(analytics):
"""Wrapper to request Google Analytics data with exponential backoff.
The makeRequest method accepts the analytics service object, makes API
requests and returns the response. If any error occurs, the makeRequest
method is retried using exponential backoff.
Args:
analytics: The analytics service object
Returns:
The API response from the makeRequest method.
"""
for n in range(0, 5):
try:
return makeRequest(analytics)
except HttpError, error:
if error.resp.reason in ['userRateLimitExceeded', 'quotaExceeded',
'internalServerError', 'backendError']:
time.sleep((2 ** n) + random.random())
else:
break
print "There has been an error, the request never succeeded."