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 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 iki şekilde çağrı yapılabileceği 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 kullanılır. Yapıları için REST arayüzü Kaynak adları bölümüne bakın.

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 önüne ekleriz:

• AdGroupId / 123 + ~ + AdId / 45678 = 123~45678 reklam kimliğine sahip bileşik reklam grubu.

İ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 işlem yapan yönetici hesabını veya kendi hesabını doğrudan 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 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ş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, v25 ve sonraki sürümlerde AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION (veya v24 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 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/v26/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 zorunludur ve 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ı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 (ö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 ü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ı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'dir ve linked-customer-id, Reklamveren hesabının müşteri kimliği olarak 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 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 başlıkları

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 veya beklenmeyen API istekleriyle ilgili sorunları gidermeye yardımcı olması için destek ekibiyle iletişime geçerken bu değeri sağlayın.