API çağrısı yapısı

Bu kılavuzda, tüm API çağrılarının ortak yapısı açıklanmaktadır.

API ile etkileşim kurmak için istemci kitaplığı kullanıyorsanız temel istek ayrıntılarını bilmeniz gerekmez. Ancak test ve hata ayıklama sırasında API çağrısı yapısı hakkında bilgi sahibi olmak faydalı olabilir.

Google Ads API, REST bağlamaları olan bir gRPC API'dir. Yani API'ye çağrı yapmanın iki yolu vardır.

Tercih edilen:

1. İsteğin gövdesini protokol arabelleği olarak oluşturun.
2. HTTP/2 kullanarak sunucuya gönderin.
3. Yanıtı bir protokol arabelleğine seri durumdan çıkarın.
4. Sonuçları yorumlama.

Dokümanlarımızın çoğunda gRPC kullanımı açıklanmaktadır.

İsteğe bağlı:

1. İsteğin gövdesini JSON nesnesi olarak oluşturun.
2. HTTP 1.1 kullanarak sunucuya gönderin.
3. Yanıtı JSON nesnesi olarak seri durumdan çıkarın.
4. Sonuçları yorumlama.

REST kullanımı hakkında daha fazla bilgi için REST arayüzü kılavuzuna bakın.

Not: Bu kılavuzda, hem gRPC hem de REST protokollerinde ortak olan yapı ve aktarım başlıkları açıklanmaktadır.

Kaynak tanımlayıcıları

Google Ads API'deki nesneler, yapılandırılmış kaynak adları ve bileşik tanımlayıcılar kullanılarak ele alınır.

Kaynak adları

API'deki çoğu nesne, kaynak adı dizeleriyle tanımlanır. Bu dizeler, REST arayüzü kullanılırken URL olarak da kullanılır. Yapıları için REST arayüzü Kaynak adları bölümüne bakın.

Önemli Nokta: Desteklenen tüm kaynaklar ve bunların yol gösterimi (resource_name) için kaynak belgelerine göz atın. Diğer hizmetler için de aynı biçim kullanılır.

Bileşik kimlikler

Bir nesnenin kimliği global olarak benzersiz değilse üst kimliği ve bir tilde (~) eklenerek bu nesne için bileşik bir kimlik oluşturulur.

Örneğin, bir AdGroupAd, customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id} kaynak adı kalıbına sahiptir. Bileşik tanımlayıcısı, üst reklam grubu kimliğini (ad_group.id) ve temel reklam kimliğini (ad_group_ad.ad.id) birleştirdiğinden, reklam grubu kimliğini reklam kimliğinin başına ekleriz:

• 123'nin AdGroupId değeri + ~ + 45678'nin AdId değeri = 123~45678'nin bileşik reklam grubu reklam kimliği.

Not: Bir AdId öğesinin birden fazla reklam grubunda paylaşılması yasaktır. Başka bir reklam grubundaki mevcut bir AdId öğesine referans veren yeni bir AdGroupAd oluşturma işlemi AdGroupAdError.AD_SHARING_NOT_ALLOWED hatasıyla başarısız oluyor.

İstek başlıkları

Bunlar, istekteki gövdeye eşlik eden HTTP üstbilgileridir (veya gRPC meta verileri):

Yetkilendirme

Bir müşteri adına işlem yapan yönetici hesabını veya doğrudan kendi hesabını yöneten reklamvereni tanımlayan Authorization: Bearer YOUR_ACCESS_TOKEN biçiminde bir OAuth 2.0 erişim jetonu eklemeniz gerekir. Erişim jetonu alma talimatlarını OAuth2 kılavuzunda bulabilirsiniz. Erişim jetonu, alındıktan sonra bir saat boyunca geçerlidir. Süresi dolduğunda erişim jetonunu yenileyerek yeni bir jeton alın. İstemci kitaplıklarımız, süresi dolan jetonları otomatik olarak yeniler.

Yetkilendirme hatalarıyla karşılaşırsanız doğru kimlik bilgilerini kullandığınızdan ve yeterli izinlere sahip olduğunuzdan emin olun. USER_PERMISSION_DENIED hatası, kimliği doğrulanmış kullanıcının istekte belirtilen müşteri hesabına erişimi olmayabileceğini gösterir. Google Cloud projeniz yalnızca Test erişimi için onaylandıysa ve üretim hesabını hedefleyen bir istek gönderirseniz API, 25. sürüm ve sonraki sürümlerde AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION (veya 24. sürüm ve önceki sürümlerde AuthorizationError.ACTION_NOT_PERMITTED) döndürür. İzinleri yönetmeyle ilgili ayrıntılar için Google Ads erişim düzeyleri başlıklı makaleyi inceleyin.

login-customer-id

Bu, istekte kullanılacak yetkili müşterinin müşteri kimliğidir ve kısa çizgi (-) içermez. Müşteri hesabına erişiminiz bir yönetici hesabı üzerinden sağlanıyorsa bu başlık zorunludur ve yönetici hesabının müşteri kimliğine ayarlanmalıdır. Yönetici hesabı üzerinden kimlik doğrulaması yaparken login-customer-id parametresini eklemezseniz AuthorizationError.USER_PERMISSION_DENIED hatası alırsınız. Bu hata türü hakkında daha fazla bilgi için sık karşılaşılan hatalar bölümünü inceleyin. Hesap erişiminin nasıl çözümlendiğine dair ayrıntılı bir açıklama için OAuth erişim modeli kılavuzuna bakın.

Önemli Terim: İşlem yapan müşteri, istek yükündeki müşteri kimliğidir. Örneğin, aşağıdaki CampaignBudgetService isteğinde işlem yapan müşteri 1234567890:

https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate

login-customer-id ayarını yapmak, oturum açtıktan sonra Google Ads kullanıcı arayüzünde bir hesap seçmeye veya sağ üstteki profil resminizi tıklamaya eşdeğerdir. Bu başlığı eklemezseniz varsayılan olarak işleten müşteri kullanılır.

Not: OAuth kimlik bilgilerinizle doğrudan erişilebilen hesapların listesini CustomerService.ListAccessibleCustomers isteği göndererek alabilirsiniz. login-customer-id, bu istek türü için gerekli değildir ve döndürülen müşteri listesi üzerinde herhangi bir etkisi yoktur.

linked-customer-id

Bu başlık zorunludur ve bağlı bir Google Ads hesabı üzerinde işlem yaparken iş ortakları (ör. üçüncü taraf uygulama analizi sağlayıcıları veya veri iş ortakları) tarafından kullanılır. Bu üstbilgi, ürün bağlantısına sahip Google Ads hesabının müşteri kimliğini belirtmelidir.

Bir iş ortağının, ürün bağlantısına dayalı olarak bir Google Ads hesabına API çağrıları yapması gereken senaryoyu ele alalım.

• Reklamveren: API çağrısı tarafından yönetilen veya güncellenen Google Ads hesabı. Reklamveren hesabının kimliği istekte belirtilir. REST'te bu, customerId yol parametresidir (ör. customers/1111111111/...). gRPC'de ise istekteki customer_id alanıdır.
• İş ortağı: İş ortağı hesabı (ör. üçüncü taraf uygulama analizi sağlayıcısı veya veri iş ortağı).
• Bağlı hesap: İş Ortağı ile ürün bağlantısı oluşturmuş olan ve İş Ortağı'na Reklamveren'e erişim izni veren Google Ads hesabı.

İş ortağı hesabına erişimi olan bir kullanıcı, reklamveren hesabındaki öğeler üzerinde işlem yapmak (ör. dönüşümleri yüklemek veya kullanıcı listelerini yönetmek) için API çağrıları yapar. Bağlı hesap, reklamveren hesabının kendisi veya reklamveren hesabının yönetici hesabı olabilir.

İstek başlıkları aşağıdaki gibi ayarlanmalıdır:

• Authorization: İş ortağına erişimi olan bir kullanıcı için OAuth 2.0 erişim jetonu.
• login-customer-id: İş ortağı hesabının müşteri kimliği. Kimliği doğrulanmış kullanıcının bu hesaba erişimi olmalıdır.
• linked-customer-id: Bağlı hesabın müşteri kimliği. Bu üstbilgi, bu isteğin yetkilendirmesinin, bağlı hesabın iş ortağıyla olan ürün bağlantısına dayandığını gösterir.

İki bağlantı senaryosu vardır:

• Reklamveren hesabının İş ortağı hesabıyla doğrudan ürün bağlantısı varsa Bağlı hesap Reklamveren'dir ve linked-customer-id, Reklamveren hesabının müşteri kimliğine ayarlanmalıdır.
• Reklamveren hesabı, İş Ortağı hesabıyla ürün bağlantısı olan bir yönetici hesabı tarafından yönetiliyorsa Bağlı hesap yönetici hesabıdır ve linked-customer-id, yöneticinin müşteri kimliğine ayarlanmalıdır.

1. örnek: Doğrudan bağlantı

Reklamveren hesabı (1111111111), iş ortağı hesabıyla (2222222222) doğrudan bağlantılıysa ve API çağrısı customers/1111111111/... değerini hedefliyorsa:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

2. örnek: Yönetici bağlantısı

Reklamveren hesabı 1111111111, yönetici hesabı 3333333333 tarafından yönetiliyorsa, yönetici hesabı 3333333333 iş ortağı hesabı 2222222222 ile bağlantılıysa ve API çağrısı customers/1111111111/... hedefleniyorsa:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Yanıt başlıkları

Yanıt gövdesiyle birlikte aşağıdaki başlıklar (veya gRPC trailing-metadata) döndürülür. Hata ayıklama amacıyla bu değerleri günlüğe kaydetmenizi öneririz.

request-id

request-id, bu isteği benzersiz şekilde tanımlayan bir dizedir. Başarısız veya beklenmeyen API istekleriyle ilgili sorunları gidermeye yardımcı olması için destek ekibiyle iletişime geçerken bu değeri sağlayın.