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:
- İstisnayı yakalayın ve günlükleri kaydedin: İstisnaları yakalayarak ve isteğe bağlı olarak API günlüklerini kaydederek başlayın.
errorslistesini inceleyin:GoogleAdsFailurenesnesindeki herGoogleAdsErroröğesine bakın.error_codevemessage, sorunun ne olduğunu size bildirir.locationdeğerini kontrol edin:locationalanı, isteğinizin hangi bölümünde sorun oluştuğunu belirlemenize yardımcı olabilir.- 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.
- İsteğinizi düzenleme: Hata mesajına göre API isteğinizi düzeltin. Örneğin,
REQUIRED_FIELD_MISSINGifadesini görüyorsanız isteğinizde bu alanı sağladığınızdan emin olun. request_idgü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_idparametresini 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.