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. Hata oluşursa yanıt bir GoogleAdsFailure nesnesi içerir. 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 belirli 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ğuyla ilgili 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 sayede kitaplık, uygulamanız tarafından yapılan tüm API çağrıları için günlük oluşturur.

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 kaydı 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 kaydı 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 uygulamanız gereken adımlar şunlardır:

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ğinizde sorunun nerede meydana geldiğini tam olarak belirlemenize yardımcı olabilir.
4. Belgeleri inceleyin: Belirli hata kodları için Sık karşılaşılan hatalar sayfasını veya hata ve hatanın nasıl çözüleceği hakkında daha fazla bilgi edinmek için Hata kodu referansı sayfası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ürseniz isteğinizde bu alanı belirttiğinizden emin olun.
6. request_id kaydetme: Bir hatayı nasıl çözeceğinizi bulamıyorsanız ve destek ekibiyle iletişime geçmeniz gerekiyorsa başarısız olan istek için tam istek ve yanıt günlüklerini ekleyin. request_id 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.