טיפול בשגיאות 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.v26.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 תוכלו לקרוא מידע נוסף על שגיאות ב-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
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors 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 "
            f"'{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#‎

כדי להפעיל את הרישום ביומן, מוסיפים את השורה הבאה ל-method‏ 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 מפורטות שיטות מתקדמות יותר לטיפול בשגיאות, כולל לוגיקה של ניסיון חוזר וכישלון חלקי.