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 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ıyla ilgili bazı bilgiler işe yarayabilir.

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:

1. İsteğin gövdesini protokol arabelleği olarak oluşturun.
2. HTTP/2 kullanarak sunucuya gönderin.
3. Yanıtı protokol arabelleğine seri durumdan çıkarma.
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 çıkarma.
4. Sonuçları yorumlama.

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

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

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ü Kaynak adları bölümüne bakın.

Bileşik kimlikler

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

Örneğin, AdGroupAd öğesinin kaynak adı kalıbı customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id} şeklindedir. Bileşik kimliği, üst reklam grubu kimliğini (ad_group.id) ve temel reklam kimliğini (ad_group_ad.ad.id) birleştirdiğinden reklam kimliğinin önüne reklam grubu kimliğini ekliyoruz:

• 123 + ~ + AdId45678 reklam grubunun AdGroupId'ı = bileşik reklam grubu 123~45678 reklamının reklam kimliği.

İstek başlıkları

Bunlar, istekteki gövdeye eşlik eden HTTP başlıklarıdır (veya gRPC meta verileri):

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 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 geçerlidir. 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.

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

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 yapılıyorsa bu başlık zorunludur ve yönetici hesabının müşteri kimliğine ayarlanmalıdır. Bir yönetici hesabı üzerinden kimlik doğrulama yaparken login-customer-id karakterini eklemezseniz AuthorizationError.USER_PERMISSION_DENIED hatası oluşur. 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üldüğüne dair ayrıntılı açıklama için OAuth erişim modeli kılavuzuna bakın.

https://googleads.googleapis.com/v25/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 başlığı eklemezseniz varsayılan olarak işleten müşteri kullanılır.

linked-customer-id

Bu başlık, bağlı bir Google Ads hesabında işlem yaparken iş ortakları (ör. üçüncü taraf uygulama analizi sağlayıcıları veya veri iş ortakları) tarafından kullanılması zorunlu olan bir başlıktır. Bu başlık, ürün bağlantısını içeren Google Ads hesabının müşteri kimliğini belirtmelidir.

Bir iş ortağının, ürün bağlantısına dayalı olarak 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 (örneğin, customers/1111111111/...). gRPC'de ise bu, 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 oluşturulmuş bir ürün bağlantısı olan ve iş ortağına reklamverene erişim izni veren Google Ads hesabı.

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

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

• Authorization: İş ortağına erişimi olan bir kullanıcının 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 başlık, bu isteğin yetkilendirmesinin, bağlı hesabın iş ortağıyla olan ürün bağlantısına dayandığını belirtir.

İ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 olur 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.

Örnek 1: Doğrudan bağlantı

Reklamveren hesabı 1111111111 ile iş ortağı hesabı 2222222222 arasında doğrudan bağlantı varsa ve API çağrısı customers/1111111111/...'yi 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ıyla 2222222222 bağlantıya sahipse ve API çağrısı customers/1111111111/... hedefliyse:

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

Yanıt üstbilgileri

Aşağıdaki başlıklar (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. Başarısız olan veya beklenmedik API istekleriyle ilgili sorunları gidermeye yardımcı olması için destek ekibiyle iletişime geçerken bu değeri sağlayın.