API hatalarını işleme

Google Ads API'ye istek gönderdiğinizde bu istek çeşitli nedenlerle başarısız olabilir. Örneğin, geçersiz bir bağımsız değişken sağlayabilir veya hesabınız yeni kampanya oluşturma sınırına ulaşmış olabilir. Bu tür durumlarda API, neyin yanlış gittiğini bildirerek hata döndürür.

Bu kılavuzda, daha sağlam uygulamalar oluşturabilmeniz için API hatalarının nasıl okunacağı ve işleneceği açıklanmaktadır.

Hata yapısı

İstemci kitaplıklarımızdan birini kullanıyorsanız API hataları istisna olarak gösterilir. Bu istisnalar, hatanın neden oluştuğunu anlamanıza yardımcı olacak ayrıntılar içerir.

Google Ads API, hata bilgilerini standart bir biçimde döndürür. Bir hata oluşursa yanıt, GoogleAdsFailure nesnesi içerir. Bu nesne, her biri belirli bir hatayı ayrıntılandıran bağımsız GoogleAdsError nesnelerinin listesini içerir.

Her GoogleAdsError nesnesi şunları sağlar:

• error_code: Hata türünü belirten belirli bir hata kodu (ör. AuthenticationError.NOT_ADS_USER).
• message: Hataya neden olan durumun kullanıcılar tarafından okunabilen açıklaması.
• trigger: Hataya neden olan değer (ör. "1234").
• location: İsteğin hangi bölümünün hataya neden olduğuna dair ayrıntılar (ör. belirli bir alan adı).

Hata listesine ek olarak, GoogleAdsFailure, hatayla sonuçlanan API isteğinin benzersiz tanımlayıcısı olan requestId içerir.

Örnek hata

Aşağıda, JSON biçimindeki bir hata örneği verilmiştir. Bu hata, 0 dizinindeki ad_group öğesinin name alanının istekte eksik olduğunu gösterir.

{
  "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 hataları hakkında daha fazla bilgi edinmek için kılavuzumuza bakın.

İstemci kitaplığı örnekleri

Aşağıdaki bölümde, çeşitli istemci kitaplıklarındaki hataların nasıl ele alınacağı gösterilmektedir.

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);
  }
}

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}");
    }
}

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
        );
    }
}

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}'.")

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

# 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};
  }
}

Günlükleri yakalama

Hataları gidermek için Google Ads API sunucusu tarafından döndürülen hata günlüklerini yakalayın ve içeriklerini inceleyin. Günlüğü etkinleştirmek ve API günlüklerini yakalamak için aşağıdaki talimatları uygulayın.

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);

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

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

Hataları ele alma

Bir hatayla karşılaşırsanız aşağıdaki adımları uygulayın:

1. İstisnayı yakalayın ve günlükleri alın: İstisnaları yakalayarak ve isteğe bağlı olarak API günlüklerini alarak başlayın.
2. errors listesini inceleyin: GoogleAdsFailure nesnesindeki her bir GoogleAdsError öğesine bakın. error_code ve message simgeleri, sorunun ne olduğunu gösterir.
3. location değerini kontrol edin: location alanı, isteğinizin hangi bölümünde sorun oluştuğunu belirlemenize yardımcı olabilir.
4. Dokümanlara bakın: Belirli hata kodlarıyla ilgili olarak hatanın ayrıntıları ve nasıl düzeltileceği hakkında daha fazla bilgi edinmek için yaygın hatalar sayfasını veya hata kodu referansının tamamını inceleyin.
5. İsteğinizi ayarlayın: Hata mesajına göre API isteğinizi düzeltin. Örneğin, REQUIRED_FIELD_MISSING simgesini görüyorsanız isteğinizde bu alanı sağladığınızdan emin olun.
6. request_id günlüğünü kaydedin: Bir hatanın nasıl çözüleceğini bulamıyorsanız ve destek ekibiyle iletişime geçmeniz gerekiyorsa başarısız olan isteğin tam istek ve yanıt günlüklerini ekleyin. request_id eklediğinizden emin olun. Bu kimlik, Google mühendislerinin Google Ads API sunucusu günlüklerinde başarısız olan istek ayrıntılarını bulmasına ve sorununuzu araştırmasına yardımcı olur.

Sonraki adımlar

• Sık karşılaşılan sorunların ve çözümlerinin listesi için Sık Karşılaşılan Hatalar'ı inceleyin.
• Yeniden deneme mantığı ve kısmi hata dahil olmak üzere daha gelişmiş hata işleme teknikleri için API Hatalarını Anlama başlıklı makaleyi inceleyin.