API hatalarını anlama

Bu kılavuzda, Google Ads API'nin hataları nasıl işlediği ve hatalarla ilgili nasıl iletişim kurduğu açıklanmaktadır. API hatalarının yapısını ve anlamını anlamak, geçersiz girişten geçici hizmet kullanılamamasına kadar sorunları düzgün bir şekilde ele alabilen sağlam uygulamalar oluşturmak için çok önemlidir.

Google Ads API, gRPC durum kodlarına dayalı olan standart Google API hata modelini kullanır. Hatayla sonuçlanan her API yanıtında aşağıdakileri içeren bir Status nesnesi bulunur:

• Sayısal bir hata kodu.
• Hata mesajı
• İsteğe bağlı, ek hata ayrıntıları.

Standart hata kodları

Google Ads API, gRPC ve HTTP tarafından tanımlanan bir dizi standart hata kodu kullanır. Bu kodlar, hata türüyle ilgili üst düzey bir gösterge sağlar. Sorunun temel doğasını anlamak için her zaman önce bu sayısal kodu kontrol etmelisiniz.

Aşağıdaki tabloda, Google Ads API'yi kullanırken karşılaşabileceğiniz en yaygın kodlar özetlenmiştir:

Bu kodlarla ilgili daha fazla bilgi için API Tasarım Kılavuzu - Hata kodları başlıklı makaleyi inceleyin.

Hata ayrıntılarını anlama

Google Ads API, üst düzey kodun ötesinde, Status nesnesinin details alanında daha ayrıntılı hata bilgileri sağlar. Bu alan genellikle, ayrı GoogleAdsError nesnelerinin listesini içeren bir GoogleAdsFailure proto'su içerir.

Her GoogleAdsFailure nesnesi şunları içerir:

• errors: Her biri belirli bir hatayı ayrıntılandıran GoogleAdsError nesnelerinin listesi.
• request_id: İsteğin benzersiz kimliği. Hata ayıklama ve destek amaçlı olarak kullanışlıdır.

Her GoogleAdsError nesnesi şunları sağlar:

• error_code: Google Ads API'ye özgü ErrorCode (yaygın hatalar) gibi daha ayrıntılı bir hata mesajı AuthenticationError.NOT_ADS_USER.
• message: Belirli hatanın kullanıcıların okuyabileceği bir açıklaması.
• trigger: Varsa hataya neden olan Value.
• location: Alan yolları da dahil olmak üzere, hatanın istekte nerede oluştuğunu açıklayan bir ErrorLocation.
• details: Yayınlanmamış hata nedenleri gibi ek ErrorDetails.

Hata ayrıntıları örneği

Hata aldığınızda istemci kitaplığınız bu ayrıntılara erişmenize olanak tanır. Örneğin, bir INVALID_ARGUMENT (Kod 3) aşağıdaki gibi ayrıntılara sahip olabilir: GoogleAdsFailure

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

Bu örnekte, üst düzey INVALID_ARGUMENT öğesine rağmen GoogleAdsFailure ayrıntıları, soruna name ve description alanlarının neden olduğunu ve nedenini (sırasıyla REQUIRED ve TOO_SHORT) gösterir.

Hata ayrıntılarını bulma

Hata ayrıntılarına erişme şekliniz, standart API çağrıları, kısmi hata veya akış kullanıp kullanmadığınıza bağlıdır.

Standart ve akış API çağrıları

Kısmi hata kullanılmadan bir API çağrısı başarısız olduğunda (akış çağrıları dahil), GoogleAdsFailure nesnesi gRPC yanıt başlıklarındaki sondaki meta verilerin bir parçası olarak döndürülür. Standart aramalar için REST kullanıyorsanız HTTP yanıtında GoogleAdsFailure döndürülür. İstemci kitaplıkları genellikle bunu GoogleAdsFailure özelliğiyle bir istisna olarak gösterir.

Kısmi hata

Kısmi hata kullanıyorsanız başarısız olan işlemlerle ilgili hatalar, yanıt başlıklarında değil, yanıtın partial_failure_error alanında döndürülür. Bu durumda, GoogleAdsFailure, yanıttaki google.rpc.Status nesnesine yerleştirilir.

Toplu işler

Toplu işlem için, iş tamamlandıktan sonra BatchJobService.ListBatchJobResults çağrılarak tek tek işlemlerle ilgili hatalar bulunabilir. Her işlem sonucu, işlem başarısız olursa hata ayrıntılarını içeren bir status alanı içerir.

Talep numarası

request-id, API isteğinizi tanımlayan benzersiz bir dizedir ve sorun giderme için gereklidir.

request-id simgesini birden fazla yerde bulabilirsiniz:

• GoogleAdsFailure: Bir API çağrısı başarısız olursa ve GoogleAdsFailure döndürülürse bu yanıt request_id içerir.
• Sonraki meta veriler: Hem başarılı hem de başarısız istekler için gRPC yanıtının sonraki meta verilerinde request-id mevcuttur.
• Yanıt başlıkları: Hem başarılı hem de başarısız istekler için request-id, başarılı akış istekleri hariç olmak üzere gRPC ve HTTP yanıt başlıklarında da kullanılabilir.
• SearchGoogleAdsStreamResponse: Yayın isteğinde bulunan her SearchGoogleAdsStreamResponse mesajında request_id alanı bulunur.

Hataları günlüğe kaydederken veya destek ekibiyle iletişime geçerken sorunların teşhis edilmesine yardımcı olması için request-id simgesini eklediğinizden emin olun.

Hata işleme ile ilgili en iyi uygulamalar

Esnek uygulamalar oluşturmak için aşağıdaki en iyi uygulamaları uygulayın:

1. Hata ayrıntılarını inceleyin: Status nesnesinin details alanını her zaman ayrıştırın ve özellikle GoogleAdsFailure değerini arayın. GoogleAdsError içindeki ayrıntılı error_code, message ve location, hata ayıklama ve kullanıcı geri bildirimi için en uygulanabilir bilgileri sağlar.

2. İstemci hatalarını sunucu hatalarından ayırt etme:

   • İstemci hataları: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED gibi kodlar. Bu durumda, istekte veya uygulamanızın durumunda/kimlik bilgilerinde değişiklik yapmanız gerekir. Sorunu çözmeden isteği yeniden göndermeyin.
   • Sunucu hataları: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN gibi kodlar. Bunlar, API hizmetiyle ilgili geçici bir soruna işaret eder.

3. Yeniden deneme stratejisi uygulayın:

   • Ne zaman yeniden denenmeli: Yalnızca UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN ve ABORTED gibi geçici sunucu hataları için yeniden deneyin.
   • Eksponansiyel geri yükleme: Yeniden denemeler arasında artan sürelerle beklemek için eksponansiyel geri yükleme algoritması kullanın. Bu, zaten stresli olan bir hizmetin aşırı yüklenmesini önlemeye yardımcı olur. Örneğin, önce 1 saniye, sonra 2 saniye, sonra 4 saniye bekleyin. Maksimum yeniden deneme sayısına veya toplam bekleme süresine ulaşana kadar bu şekilde devam edin.
   • Jitter: Birçok istemcinin aynı anda yeniden denediği "gürleyen kalabalık" sorununu önlemek için geri çekilme gecikmelerine küçük bir rastgele "jitter" miktarı ekleyin.

4. Günlüğü ayrıntılı olarak tutun: Tüm ayrıntılar, özellikle de istek kimliği dahil olmak üzere hata yanıtının tamamını günlüğe kaydedin. Bu bilgiler, hata ayıklama ve gerektiğinde Google Destek Ekibi'ne sorun bildirme için gereklidir.

5. Kullanıcı geri bildirimi sağlayın: Belirli GoogleAdsError kodlarına ve mesajlarına göre uygulamanızın kullanıcılarına net ve faydalı geri bildirimler verin. Örneğin, yalnızca "Bir hata oluştu" demek yerine "Kampanya adı zorunludur" veya "Sağlanan reklam grubu kimliği bulunamadı" diyebilirsiniz.

Bu yönergeleri uygulayarak Google Ads API'nin döndürdüğü hataları etkili bir şekilde teşhis edip işleyebilir, böylece daha kararlı ve kullanıcı dostu uygulamalar oluşturabilirsiniz.