標準錯誤回應
如果 Provisioning 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 錯誤，使用不同資料檢視 (設定檔) 的同一項查詢不一定會導致錯誤。
實行指數輪詢
指數輪詢是用戶端定期重試失敗的要求的程序，會逐漸增加一段時間。這是網路應用程式的標準錯誤處理策略。Provisioning 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."