טיפול בשגיאות API

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

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

מבנה השגיאה

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

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

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

  • error_code: קוד שגיאה ספציפי שמציין את סוג השגיאה, למשל AuthenticationError.NOT_ADS_USER.
  • message: תיאור קריא לאנשים של הסיבה להתרחשות השגיאה.
  • trigger: הערך שגרם לשגיאה, כמו '1234'.
  • location: פרטים על החלק בבקשה שגרם לשגיאה, כמו שם שדה ספציפי.

בנוסף לרשימת השגיאות, התג GoogleAdsFailure מכיל את התג requestId, שהוא מזהה ייחודי של בקשת ה-API שהובילה לשגיאה.

דוגמה לשגיאה

דוגמה לשגיאה בפורמט JSON. השגיאה הזו מציינת שהשדה name של ad_group באינדקס 0 חסר בבקשה.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

מידע נוסף על שגיאות ב-API זמין במדריך.

דוגמאות לספריות לקוח

בקטע הבא מוסבר איך לטפל בשגיאות בספריות לקוח שונות.

Java

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an API request.
  // Instances of this exception have a message and a GoogleAdsFailure that contains a
  // collection of GoogleAdsErrors that indicate the underlying causes of the
  // GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

C#‎

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

PHP

try {
  // Make an API call.
  ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

Python

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(f"\tError with message '{error.message}' and code '{error.error_code}'.")

Ruby

begin
    # Make an API call.
    ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
    puts "API call failed with request ID: #{e.request_id}"
    e.failure.errors.each do |error|
        puts "\t#{error.error_code}: #{error.message}"
    end
end

Perl

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n", [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

איך מתעדים יומנים

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

Java

הוראות מפורטות זמינות במדריך לרישום ביומן של ספריית לקוח Java.

C#‎

כדי להפעיל את הרישום ביומן, מוסיפים את השורה הבאה לשיטה Main לפני שמבצעים קריאות ל-API. כך מוודאים שכל הספרייה יוצרת יומנים לכל קריאות ה-API שמתבצעות על ידי האפליקציה.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

אפשרויות נוספות מפורטות במדריך לרישום ביומן של ספריית ‎.NET.

PHP

אפשר להגדיר את הרישום ביומן בקובץ google_ads_php.ini של ספריית הלקוח. מגדירים את logLevel ל-NOTICE כדי להתחיל לתעד את יומני השגיאות המפורטים.

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

הוראות מפורטות במדריך לרישום ביומן של ספריית הלקוח של PHP.

Python

אפשר להגדיר את הרישום ביומן בקובץ google-ads.yaml של ספריית הלקוח. מגדירים את רמת הרישום ל-DEBUG כדי להתחיל לתעד את יומני השגיאות המפורטים.

אפשרויות נוספות מפורטות במדריך לרישום ביומן של ספריות Python.

Ruby

אפשר להגדיר את הרישום ביומן בקובץ google_ads_config.rb של ספריית הלקוח. מגדירים את רמת הרישום ל-INFO כדי להתחיל לתעד את יומני השגיאות המפורטים.

אפשרויות נוספות מפורטות במדריך לרישום ביומן של ספריית Ruby.

Perl

כדי לאתחל את הרישום ביומן, מוסיפים את השורה הבאה בסקריפט Perl לפני שמבצעים קריאות ל-API.

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

אפשר לעיין במדריך לרישום ביומן של ספריית Perl כדי לראות אפשרויות נוספות.

curl

כברירת מחדל, הפקודה curl מדפיסה את התשובות שנכשלו ל-stderr.

איך מטפלים בשגיאות

אם נתקלתם בשגיאה, הנה השלבים שצריך לבצע:

  1. תופסים את החריג ומתעדים את היומנים: מתחילים בתפיסת החריגים ומתעדים את יומני ה-API (אופציונלי).
  2. בודקים את רשימת errors: בודקים כל GoogleAdsError באובייקט GoogleAdsFailure. השגיאות יופיעו בerror_code ובmessage.
  3. בודקים את הערך של location: השדה location יכול לעזור לכם לזהות את המיקום בבקשה שבו התרחשה הבעיה.
  4. עיון במסמכי התיעוד: כדי לקבל פרטים נוספים על שגיאות ספציפיות ועל אופן התיקון שלהן, אפשר לעיין בדף השגיאות הנפוצות או בהפניה המלאה לקודי שגיאה.
  5. שינוי הבקשה: בהתאם להודעת השגיאה, מתקנים את בקשת ה-API. לדוגמה, אם אתם רואים REQUIRED_FIELD_MISSING, אתם צריכים לציין את השדה הזה בבקשה.
  6. רישום ביומן של request_id: אם לא הצלחתם להבין איך לפתור שגיאה ואתם צריכים לפנות לתמיכה, עליכם לצרף את יומני הבקשות והתגובות המלאים של הבקשה שנכשלה. חשוב לכלול את request_id. המזהה הזה עוזר למהנדסי Google לאתר את פרטי הבקשה שנכשלה ביומני השרת של Google Ads API ולבדוק את הבעיה.

השלבים הבאים

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