Bu kılavuzda, tüm API çağrılarının ortak yapısı açıklanmaktadır.
API ile etkileşimde bulunmak için bir istemci kitaplığı kullanıyorsanız temel istek ayrıntıları konusunda endişelenmenize gerek yoktur. Ancak bunlar hakkında biraz bilgi sahibi olmak test ve hata ayıklama sırasında 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 protokol arabelleği olarak oluşturun, HTTP/2 kullanarak sunucuya gönderin, bir protokol arabelleğinde yanıtı seri durumdan çıkarın ve sonuçları yorumlayın. Belgelerimizin çoğu, gRPC'nin nasıl kullanılacağını açıklar.
[İsteğe bağlı] İsteğin gövdesini bir JSON nesnesi olarak oluşturun, HTTP 1.1 kullanarak sunucuya gönderin, yanıtı JSON nesnesi olarak seri durumdan çıkarın ve sonuçları yorumlayın. 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 görevi de görür. Yapıları için REST arayüzünün Kaynak Adlarına bakın.
Birleşik kimlikler
Bir nesnenin kimliği genel olarak benzersiz değilse bu nesnenin birleşik kimliği, üst kimliğinin ve yaklaşık işareti (~) eklenerek oluşturulur.
Örneğin, bir reklam grubunun reklam kimliği genel olarak benzersiz olmadığından benzersiz bir birleşik kimlik oluşturmak için üst nesne (reklam grubu) kimliğini başına ekleriz:
AdGroupId
/123
+~
+AdGroupAdId
/45678
=123~45678
birleşik reklam grubu reklam kimliği.
İstek başlıkları
Bunlar, istekte gövdeye eşlik eden HTTP üst bilgileri (veya grpc meta verileri)dir:
Yetkilendirme
Müşteri adına hareket eden bir yönetici hesabını veya doğrudan kendi hesabını 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 sonra bir saat süreyle geçerlidir. Bu jetonların süresi dolduğunda yeni bir jeton almak için erişim jetonunu yenileyin. İstemci kitaplıklarımızın, süresi dolmuş jetonları otomatik olarak yenilediğini unutmayın.
geliştirici jetonu
Geliştirici jetonu, bir Google Ads API geliştiricisini benzersiz bir şekilde tanımlayan 22 karakterli bir dizedir. Örnek bir geliştirici jetonu dizesidir: ABcdeFGH93KL-NOPQ_STUv
. Geliştirici jetonu developer-token : ABcdeFGH93KL-NOPQ_STUv
biçiminde olmalıdır.
login-customer-id
Bu, istekte kullanılacak yetkili müşterinin kimliğidir (kısa çizgi (-
) olmadan). 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ği olarak ayarlanmalıdır.
https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate
login-customer-id
özelliğini ayarlamak, oturum açtıktan veya sağ üstteki profil resminizi tıkladıktan sonra Google Ads kullanıcı arayüzünde hesap seçmeyle eşdeğerdir. Bu başlığı eklemezseniz varsayılan olarak çalışan müşteri olur.
bağlı-müşteri-kimliği
Bu başlık, yalnızca üçüncü taraf uygulama analizi sağlayıcıları tarafından bağlı bir Google Ads hesabına dönüşüm yüklerken kullanılır.
A
hesabındaki kullanıcıların, B
hesabı için bir ThirdPartyAppAnalyticsLink
üzerinden varlıklarına okuma ve düzenleme erişimi sağladığı senaryoyu inceleyin.
Bağlandıktan sonra, B
hesabındaki bir kullanıcı, bağlantı tarafından sağlanan izinlere tabi olarak A
hesabında API çağrıları yapabilir. Bu durumda, A
hesabının API çağrısı izinleri, diğer API çağrılarında kullanılan yönetici-hesap ilişkisi yerine B
hesabına üçüncü taraf bağlantısıyla belirlenir.
Üçüncü taraf uygulama analizi sağlayıcısı, aşağıdaki şekilde bir API çağrısı yapar:
linked-customer-id
: Verileri yükleyen üçüncü taraf uygulama analizi hesabı (hesapB
).customer-id
: Verilerin yüklendiği Google Ads hesabı (A
hesabı).login-customer-id
veAuthorization
üstbilgisi:B
hesabı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 üst bilgiler (veya grpc pathing-metadata) yanıt gövdesiyle 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.