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'nin 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.

Not: Bu kılavuzda hem gRPC hem de REST protokollerinde ortak olan yapı ve aktarım üstbilgileri açıklanmaktadır.

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ını görmek için REST arayüzünün Kaynak Adları bölümüne bakın.

Önemli Bilgi: Desteklenen tüm kaynaklar ve bunların yol gösterimi (resource_name) için kaynaklar belgelerine göz atın. Diğer hizmetler için de aynı biçim kullanılır.

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, 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:

• 123 AdGroupId + 45678 ~ + 45678 AdGroupAdId = 123~45678 reklam grubunun bileşik reklam kimliği.

İstek üst bilgileri

Bunlar, istekteki gövdeye eşlik eden HTTP üstbilgileridir (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 sonra 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 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. İzinleri yönetme hakkında ayrıntılı bilgi için Google Ads Erişim Düzeyleri başlıklı makaleyi inceleyin.

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

Önemli Terim: İşlemi yapan müşteri, istek yükündeki müşteri kimliğidir. Örneğin, aşağıdaki CampaignBudgetService isteğinde işlem yapan müşteri 1234567890'dır:

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

login-customer-id ayarını yapmak, Google Ads kullanıcı arayüzünde oturum açtıktan sonra veya sağ üstteki profil resminizi tıkladıktan sonra bir hesap seçmeye eşdeğerdir. Bu üstbilgiyi eklemezseniz varsayılan olarak operating customer kullanılır.

Not: CustomerService.ListAccessibleCustomers isteği göndererek OAuth kimlik bilgilerinizle doğrudan erişilebilen hesapların listesini alabilirsiniz. login-customer-id, bu istek türü için gerekli değildir ve döndürülen müşteri listesi üzerinde herhangi bir etkisi yoktur.

linked-customer-id

Bu başlık gereklidir 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 başlık, ürün bağlantısı olan 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 oluşturulmuş bir ürün bağlantısı olan ve iş ortağına reklamverene erişim izni veren Google Ads hesabı.

İş ortağına erişimi olan bir kullanıcı, reklamverendeki öğ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, reklamverenin kendisi veya reklamverenin 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 OAuth2 jetonu.
• developer-token: API uygulamasının geliştirici jetonu, genellikle iş ortağıyla ilişkilendirilir.
• login-customer-id: İş ortağı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ı gösterir.

İki bağlantı senaryosu vardır:

• Reklamverenin İş Ortağı ile doğrudan ürün bağlantısı varsa Bağlı hesap Reklamveren'dir ve linked-customer-id, Reklamverenin müşteri kimliği olarak ayarlanmalıdır.
• Reklamveren, İş Ortağı ile ü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ı

1111111111 reklamvereni ile 2222222222 iş ortağı arasında doğrudan bağlantı varsa ve API çağrısı customers/1111111111/...'yi hedefliyorsa:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

2. örnek: Yönetici bağlantısı

Reklamveren 1111111111, Yönetici 3333333333 tarafından yönetiliyorsa, Yönetici 3333333333'nın İş Ortağı 2222222222 ile bağlantısı varsa ve API çağrısı customers/1111111111/...'ü hedefliyorsa:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_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.