הסבר על שגיאות 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.v17.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, וכך ליצור אפליקציות יציבות וידידותיות יותר למשתמשים.