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ş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.

1. [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.

2. [İ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ı (hesap B).
• customer-id: Verilerin yüklendiği Google Ads hesabı (A hesabı).
• login-customer-id ve Authorization ü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.