Bu kılavuzda, tüm API çağrılarının ortak yapısı açıklanmaktadır.
API ile etkileşim kurmak için bir 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. Bu, API'ye çağrı yapmanın iki yolu olduğu anlamına gelir.
Tercih edilen:
İsteğin gövdesini protocol buffer olarak oluşturun.
HTTP/2 kullanarak sunucuya gönderin.
Yanıtı protokol arabelleğine seri durumdan çıkarma.
Sonuçları yorumlama.
Dokümanlarımızın çoğunda gRPC'nin kullanımı açıklanır.
İsteğe bağlı:
İsteğin gövdesini JSON nesnesi olarak oluşturun.
HTTP 1.1 kullanarak sunucuya gönderin.
Yanıtı JSON nesnesi olarak seri durumdan çıkarma.
Sonuçları yorumlama.
REST'i kullanma hakkında daha fazla bilgi için REST arayüzü kılavuzuna bakın.
Kaynak adları
API'deki çoğu nesne, kaynak adı dizeleriyle tanımlanır. Bu dizeler, REST arayüzü kullanılırken URL olarak da işlev görür. Yapıları için REST arayüzünün Kaynak Adları bölümüne bakın.
Bileşik kimlikler
Bir nesnenin kimliği genel olarak benzersiz değilse bu nesne için bir bileşik kimlik, üst kimliği ve tilde işareti (~) eklenerek oluşturulur.
Örneğin, bir reklam grubu reklam kimliği genel olarak benzersiz olmadığından benzersiz bir bileşik kimlik oluşturmak için üst nesne (reklam grubu) kimliğini başına ekleriz:
123AdGroupId+45678~+AdGroupAdId=123~45678reklam grubu reklam kimliği.
İstek başlıkları
Bunlar, istekteki gövdeye eşlik eden HTTP üst bilgileridir (veya grpc metadata):
Yetkilendirme
Bir müşteri adına hareket eden bir yönetici hesabını veya kendi hesabını doğrudan yöneten bir reklamvereni tanımlayan Authorization: Bearer YOUR_ACCESS_TOKEN biçiminde bir OAuth2 erişim jetonu eklemeniz gerekir. Erişim jetonu alma talimatlarını OAuth2 kılavuzunda bulabilirsiniz. Erişim jetonu, alındıktan sonraki bir saat boyunca geçerlidir. Süresi dolduğunda yeni bir erişim jetonu almak için erişim jetonunu yenileyin. İstemci kitaplıklarımızın süresi dolan jetonları otomatik olarak yenilediğini unutmayın.
developer-token
Geliştirici jetonu, bir Google Ads API geliştiricisini benzersiz şekilde tanımlayan 22 karakterlik bir dizedir. Örnek bir geliştirici jetonu dizesi:
ABcdeFGH93KL-NOPQ_STUv. Geliştirici jetonu, developer-token : ABcdeFGH93KL-NOPQ_STUv biçiminde eklenmelidir.
login-customer-id
Bu, istekte kullanılacak yetkili müşterinin tire içermeyen müşteri kimliğidir (-). 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.
https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate
login-customer-id ayarını yapmak, giriş yaptıktan sonra Google Ads kullanıcı arayüzünde bir hesap seçmeye veya sağ üstteki profil resminizi tıklamaya eşdeğerdir. Bu üstbilgiyi eklemezseniz varsayılan olarak operating
customer kullanılır.
linked-customer-id
Bu başlık yalnızca [third-party app analytics providers when uploading conversions to a linked Google Ads account tarafından kullanılır.
A hesabındaki kullanıcıların, ThirdPartyAppAnalyticsLink aracılığıyla B hesabına öğeleri için okuma ve düzenleme erişimi sağladığı senaryoyu ele alalım.
Bağlantı oluşturulduktan sonra, B hesabındaki bir kullanıcı, bağlantı tarafından sağlanan izinlere tabi olarak A hesabına karşı API çağrıları yapabilir. Bu durumda, A hesabına yönelik API çağırma izinleri, diğer API çağrılarında kullanılan yönetici hesabı ilişkisi yerine B hesabına yönelik üçüncü taraf bağlantısı tarafından belirlenir.
Üçüncü taraf uygulama analizi sağlayıcısı, API çağrısını aşağıdaki şekilde yapar:
linked-customer-id: Verileri yükleyen üçüncü taraf uygulama analizi hesabı (hesapB).customer-id: Verilerin yüklendiği Google Ads hesabı (hesapA).login-customer-idveAuthorizationüstbilgisi:Bhesabına erişimi olan bir kullanıcıyı tanımlamak için kullanılan değerlerin bir kombinasyonu.
Yanıt başlıkları
Aşağıdaki üstbilgiler (veya grpc trailing-metadata) yanıt gövdesiyle birlikte 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.