הסבר על שגיאות API

במדריך הזה מוסבר איך Google Ads API מטפל בשגיאות ומעביר אותן. הבנה של המבנה והמשמעות של שגיאות ב-API היא חיונית לבניית אפליקציות חזקות שיכולות לטפל בבעיות בצורה חלקה, החל מקלט לא תקין ועד לזמינות זמנית של השירות.

‫Google Ads API פועל לפי מודל השגיאות הרגיל של Google API, שמבוסס על קודי סטטוס של gRPC. כל תשובת API שמובילה לשגיאה כוללת אובייקט Status שמכיל:

• קוד שגיאה מספרי.
• הודעת שגיאה.
• פרטי שגיאה נוספים (אופציונלי).

קודי שגיאה קנוניים

ב-Google Ads API נעשה שימוש בקבוצה של קודי שגיאה קנוניים שמוגדרים על ידי gRPC ו-HTTP. הקודים האלה מספקים אינדיקציה כללית לגבי סוג השגיאה. תמיד צריך לבדוק קודם את הקוד המספרי הזה כדי להבין את המהות הבסיסית של הבעיה.

בטבלה הבאה מפורטים הקודים הנפוצים ביותר שאולי תיתקלו בהם כשמשתמשים ב-Google Ads API:

פרטים נוספים על הקודים האלה זמינים במאמר מדריך לעיצוב API – קודי שגיאה.

הסבר על פרטי השגיאה

בנוסף לקוד ברמה העליונה, Google Ads API מספק מידע ספציפי יותר על שגיאות בשדה details של האובייקט Status. השדה הזה מכיל לרוב פרוטו של GoogleAdsFailure, שכולל רשימה של אובייקטים בודדים של GoogleAdsError.

כל אובייקט GoogleAdsFailure מכיל:

• ‫errors: רשימה של אובייקטים מסוג GoogleAdsError, שכל אחד מהם מפרט שגיאה ספציפית שהתרחשה.
• ‫request_id: מזהה ייחודי של הבקשה, שימושי למטרות ניפוי באגים ותמיכה.

כל אובייקט GoogleAdsError מספק את הפרטים הבאים:

• ‫errorCode: קוד שגיאה ספציפי ל-Google Ads API, ברמת פירוט גבוהה יותר, כמו AuthenticationError.NOT_ADS_USER.
• ‫message: תיאור של השגיאה הספציפית שקריא לאנשים.
• ‫trigger: הערך שגרם לשגיאה, אם רלוונטי.
• ‫location: תיאור של המקום שבו התרחשה השגיאה בבקשה, כולל נתיבי השדות.
• ‫details: פרטים נוספים על השגיאה, כמו סיבות לשגיאות שלא פורסמו.

דוגמה לפרטי שגיאה

כשמתקבלת שגיאה, ספריית הלקוח מאפשרת לכם לגשת לפרטים האלה. לדוגמה, יכול להיות שלקוד INVALID_ARGUMENT (קוד 3) יהיו פרטים כמו GoogleAdsFailure:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

בדוגמה הזו, למרות INVALID_ARGUMENT ברמה העליונה, הפרטים של GoogleAdsFailure מציינים שהשדות name ו-description גרמו לבעיה, ומסבירים למה (REQUIRED ו-TOO_SHORT, בהתאמה).

איפה אפשר למצוא את פרטי השגיאה

הדרך שבה ניגשים לפרטי השגיאה תלויה בשאלה אם משתמשים בקריאות API רגילות, בכשל חלקי או בסטרימינג.

קריאות ל-API רגילות וקריאות ל-API של סטרימינג

כשקריאה ל-API נכשלת בלי שימוש בכשל חלקי, כולל קריאות להזרמה, האובייקט GoogleAdsFailure מוחזר כחלק מהמטא-נתונים בסוף כותרות התגובה של gRPC. אם אתם משתמשים ב-REST לשיחות רגילות, הערך GoogleAdsFailure מוחזר בתגובת ה-HTTP. בדרך כלל, ספריות לקוח מציגות את זה כחריגה עם מאפיין GoogleAdsFailure.

כשל חלקי

אם אתם משתמשים בכשל חלקי, השגיאות של פעולות שנכשלו מוחזרות בשדה partial_failure_error של התגובה, ולא בכותרות התגובה. במקרה הזה, האובייקט GoogleAdsFailure מוטמע באובייקט google.rpc.Status בתשובה.

משימות באצווה

בעיבוד באצווה, אפשר לאחזר את התוצאות של משימת האצווה אחרי שהיא מסתיימת כדי לראות את השגיאות בפעולות ספציפיות. תוצאת כל פעולה תכלול שדה status עם פרטי השגיאה אם הפעולה נכשלה.

מזהה בקשה

המחרוזת request-id היא מחרוזת ייחודית שמזהה את בקשת ה-API שלכם, והיא חיונית לפתרון בעיות.

אפשר למצוא את request-id בכמה מקומות:

• ‫GoogleAdsFailure: אם קריאה ל-API נכשלת ומוחזרת GoogleAdsFailure, היא תכיל request_id.
• מטא-נתונים מסוג trailing: גם בבקשות שהצליחו וגם בבקשות שנכשלו, request-id זמין במטא-נתונים מסוג trailing של תגובת gRPC.
• כותרות תגובה: גם במקרה של בקשות מוצלחות וגם במקרה של בקשות שנכשלו, הערך request-id זמין גם בכותרות התגובה של gRPC ובתגובות HTTP, למעט במקרה של בקשות סטרימינג מוצלחות.
• ‫SearchGoogleAdsStreamResponse: בבקשות סטרימינג, כל הודעה SearchGoogleAdsStreamResponse מכילה שדה request_id.

כשרושמים שגיאות ביומן או פונים לתמיכה, חשוב לכלול את request-id כדי לעזור באבחון בעיות.

שיטות מומלצות לטיפול בשגיאות

כדי ליצור אפליקציות עמידות, כדאי להטמיע את השיטות המומלצות הבאות:

1. בדיקת פרטי השגיאה: תמיד צריך לנתח את השדה details של האובייקט Status, ובמיוחד לחפש את GoogleAdsFailure. הנתונים המפורטים errorCode, message ו-location בתוך GoogleAdsError מספקים את המידע הכי שימושי לניפוי באגים ולמשוב משתמשים.

2. הבחנה בין שגיאות בצד הלקוח לבין שגיאות בצד השרת:

   • שגיאות בצד הלקוח: קודים כמו INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. במקרים כאלה, צריך לבצע שינויים בבקשה או בסטטוס/בפרטי הכניסה של האפליקציה. אל תנסו לשלוח את הבקשה שוב בלי לפתור את הבעיה.
   • שגיאות בשרת: קודים כמו UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. ההודעות האלה מצביעות על בעיה זמנית בשירות ה-API.

3. הטמעה של אסטרטגיה של ניסיון חוזר:

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

4. רישום מקיף ביומן: רישום של תגובת השגיאה המלאה, כולל כל הפרטים, במיוחד מזהה הבקשה. המידע הזה חיוני לניפוי באגים ולדיווח על בעיות לתמיכה של Google, אם צריך.

5. לספק משוב למשתמשים: על סמך הקודים וההודעות הספציפיים של GoogleAdsError, צריך לספק משוב ברור ומועיל למשתמשים באפליקציה. לדוגמה, במקום להציג רק את ההודעה "אירעה שגיאה", אפשר להציג את ההודעה "נדרש שם קמפיין" או "לא נמצא מזהה קבוצת המודעות שצוין".

אם תפעלו לפי ההנחיות האלה, תוכלו לאבחן ולטפל ביעילות בשגיאות שמוחזרות על ידי Google Ads API, וכך ליצור אפליקציות יציבות וידידותיות יותר למשתמשים.