תגובות לשגיאות

תגובות רגילות לשגיאות

אם הבקשה של Management 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 הנתון הזה מציין שהשאילתה לא הייתה חוקית. למשל, מזהה ההורה חסר או שהשילוב של המאפיינים או המדדים המבוקשים לא היה חוקי. אין לנסות שוב ללא תיקון הבעיה. צריך לבצע שינויים בשאילתת ה-API כדי שהיא תפעל.
401 invalidCredentials מציין שאסימון האימות לא חוקי או שתוקפו פג. אין לנסות שוב ללא תיקון הבעיה. עליך לקבל אסימון אימות חדש.
403 insufficientPermissions מציין שלמשתמש אין את ההרשאות המתאימות לישות שצוינה בשאילתה. אין לנסות שוב ללא תיקון הבעיה. יש צורך בהרשאות מספיקות כדי לבצע את הפעולה בישות שצוינה.
403 dailyLimitExceeded השדה הזה מציין שהמשתמש חרג מהמכסה היומית (לכל פרויקט או לכל תצוגה מפורטת (פרופיל)). אין לנסות שוב ללא תיקון הבעיה. ניצלת את כל המכסה היומית. מידע נוסף זמין בקטע מגבלות ומכסות של API.
403 userRateLimitExceeded הפרמטר מציין שחרגת מהמגבלה של שאילתות ל-100 שניות לכל משתמש. ערך ברירת המחדל שמוגדר ב-Google API Console הוא 100 שאילתות ל-100 שניות לכל משתמש. אפשר להגדיל את המגבלה הזו במסוף Google API ל-1,000 לכל היותר. אפשר לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). יש להאט את קצב שליחת הבקשות.
403 rateLimitExceeded הסטטוס מציין שחרגת ממגבלות הקצב של שאילתות לכל 100 שניות בפרויקט. אפשר לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). יש להאט את קצב שליחת הבקשות.
403 quotaExceeded מציין שהגעתם ל-10 הבקשות הבו-זמניות לכל תצוגה מפורטת (פרופיל) ב-Core Reporting API. אפשר לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). יש להמתין לפחות בקשה אחת בתהליך כדי שהתצוגה המפורטת (פרופיל) הזו תושלם.
500 internalServerError אירעה שגיאת שרת פנימית לא צפויה. אין לנסות שוב לבצע את השאילתה הזו יותר מפעם אחת.
503 backendError השרת החזיר שגיאה. אין לנסות שוב לבצע את השאילתה הזו יותר מפעם אחת.

טיפול ב-500 או 503 תגובות

השגיאה 500 או 503 עלולה להיגרם במהלך עומס כבד או בבקשות גדולות יותר מורכבות. בבקשות גדולות יותר, כדאי לבקש נתונים לפרק זמן קצר יותר. כדאי גם לשקול להטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff). התדירות של השגיאות האלה עשויה להיות תלויה בתצוגה המפורטת (פרופיל) ובכמות של נתוני הדיווח המשויכים לתצוגה המפורטת הזו. שאילתה שגורמת לשגיאה 500 או 503 בתצוגה מפורטת אחת (פרופיל) לא בהכרח תגרום לשגיאה באותה שאילתה עם תצוגה מפורטת אחרת (פרופיל).

הטמעת השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

השהיה מעריכית לפני ניסיון חוזר (exponential backoff) הוא התהליך של לקוח שמנסה מדי פעם לשלוח בקשה שנכשלה למשך פרק זמן הולך וגדל. זוהי אסטרטגיה סטנדרטית לטיפול בשגיאות באפליקציות רשת. ממשק ה-API לניהול מתוכנן כך שלקוחות שיבחרו לנסות שוב בקשות שנכשלו יש לעשות זאת באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). מעבר ל'חובה', השימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) מגביר את היעילות של השימוש ברוחב הפס, מצמצם את מספר הבקשות הנדרשות כדי לקבל תגובה מוצלחת ומגדיל את תפוקת הבקשות בסביבות בו-זמניות.

התהליך להטמעת השהיה מעריכית פשוטה לפני ניסיון חוזר הוא:

  1. שליחת בקשה ל-API
  2. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
  3. צריך להמתין שנייה אחת + random_number_milliseconds שניות
  4. ניסיון חוזר של הבקשה
  5. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
  6. המתנה של 2 שניות + random_number_milliseconds שניות
  7. ניסיון חוזר של הבקשה
  8. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
  9. המתנה של 4 שניות + random_number_milliseconds שניות
  10. ניסיון חוזר של הבקשה
  11. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
  12. המתנה של 8 שניות + random_number_milliseconds שניות
  13. ניסיון חוזר של הבקשה
  14. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
  15. המתנה של 16 שניות + random_number_milliseconds שניות
  16. ניסיון חוזר של הבקשה
  17. אם עדיין מופיעה הודעת שגיאה, עוצרים ורושמים את השגיאה.

בתהליך שלמעלה, random_number_milliseconds הוא מספר אקראי של 1,000 או פחות אלפיות השנייה. הפעולה הזו נדרשת כדי למנוע שגיאות נעילה מסוימות בהטמעות מקבילות מסוימות. צריך להגדיר מחדש את 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."