API hatalarını işleme

Google Ads API'ye gönderdiğiniz istekler çeşitli nedenlerle başarısız olabilir. Örneğin, geçersiz bir bağımsız değişken sağlamış olabilirsiniz veya hesabınız yeni kampanya oluşturma sınırına ulaşmış olabilir. Bu gibi durumlarda API, sorunun ne olduğunu bildirmek için bir hata döndürür.

Bu kılavuzda, daha sağlam uygulamalar oluşturabilmeniz için API hatalarını nasıl okuyacağınız ve ele alacağınız 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ıtta GoogleAdsFailure nesnesi yer alır. Bu nesne, her biri belirli bir hatayı ayrıntılı olarak açıklayan bağımsız GoogleAdsError nesnelerinin listesini içerir.

Her GoogleAdsError nesnesi şunları sağlar:

  • error_code: Hatanın türünü belirten özel bir hata kodu (ör. AuthenticationError.NOT_ADS_USER).
  • message: Hatanın neden oluştuğunun 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 bir requestId içerir.

Örnek hata

JSON biçimindeki bir hata örneğini aşağıda görebilirsiniz. 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.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 hataları hakkında daha fazla bilgi edinmek için API hatalarını anlama başlıklı makaleyi inceleyin.

İstemci kitaplığı örnekleri

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

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

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ük kaydını etkinleştirmek ve API günlüklerini yakalamak için aşağıdaki talimatları uygulayın.

Java

Talimatlar için Java istemci kitaplığı günlük kaydı kılavuzuna bakın.

C#

Herhangi bir API çağrısı yapmadan önce Main yöntemine aşağıdaki satırı ekleyerek günlük kaydını başlatabilirsiniz. Bu, kitaplığın uygulamanız tarafından yapılan tüm API çağrıları için günlük oluşturmasını sağlar.

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

Ek seçenekler için .NET kitaplığı günlük kaydı kılavuzuna bakın.

PHP

Günlük kaydı yapılandırmasını istemci kitaplığınızın google_ads_php.ini dosyasında ayarlayabilirsiniz. Ayrıntılı hata günlüklerini yakalamaya başlamak için logLevel değerini NOTICE olarak ayarlayın.

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

Talimatlar için PHP istemci kitaplığı günlük kaydı kılavuzuna bakın.

Python

Günlük yapılandırmasını istemci kitaplığınızın google-ads.yaml dosyasında ayarlayabilirsiniz. Ayrıntılı hata günlüklerini yakalamaya başlamak için günlük kaydı düzeyini DEBUG olarak ayarlayın.

Ek seçenekler için Python kitaplığı günlük kaydı kılavuzuna bakın.

Ruby

Günlük yapılandırmasını istemci kitaplığınızın google_ads_config.rb dosyasında ayarlayabilirsiniz. Ayrıntılı hata günlüklerini yakalamaya başlamak için günlük kaydı düzeyini INFO olarak ayarlayın.

Ek seçenekler için Ruby kitaplığı günlük kaydı kılavuzuna bakın.

Perl

Günlük kaydını başlatmak için herhangi bir API çağrısı yapmadan önce Perl komut dosyanıza aşağıdaki satırı ekleyin.

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

Ek seçenekler için Perl kitaplığı günlük kaydı kılavuzuna bakın.

curl

curl, başarısız yanıtları varsayılan olarak stderr dosyasına yazdırır.

Hataları ele alma

Bir hatayla karşılaşırsanız şu adımları uygulayın:

  1. İstisnayı yakalayın ve günlükleri kaydedin: İstisnaları yakalayarak ve isteğe bağlı olarak API günlüklerini kaydederek başlayın.
  2. errors listesini inceleyin: GoogleAdsFailure nesnesindeki her GoogleAdsError öğesine bakın. error_code ve message, sorunun ne olduğunu size bildirir.
  3. location değerini kontrol edin: location alanı, isteğinizin hangi bölümünde sorun oluştuğunu belirlemenize yardımcı olabilir.
  4. Belgeleri inceleyin: Belirli hata kodları için yaygın hatalar sayfasını veya hata ve hatanın nasıl çözüleceği hakkında daha fazla bilgi edinmek için hata kodu referansının tamamını inceleyin.
  5. İsteğinizi düzenleme: Hata mesajına göre API isteğinizi düzeltin. Örneğin, REQUIRED_FIELD_MISSING ifadesini görüyorsanız isteğinizde bu alanı sağladığınızdan emin olun.
  6. request_id günlüğünü kaydetme: Bir hatayı nasıl çözeceğinizi 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 parametresini eklediğinizden emin olun. Bu kimlik, Google mühendislerinin Google Ads API sunucu günlüklerinde başarısız istek ayrıntılarını bulmasına ve sorununuzu incelemesine 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 bölümünü 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.