Bu kılavuzda, Google Ads API'yi oluşturan temel bileşenler tanıtılmaktadır. Google Ads API, kaynaklar ve hizmetlerden oluşur. Kaynak, bir Google Ads öğesini temsil ederken hizmetler, Google Ads öğelerini alır ve değiştirir.
Nesne hiyerarşisi
Google Ads hesabı, bir nesne hiyerarşisi olarak görüntülenebilir.
Bir hesabın üst düzey kaynağı customer'dır.
Her müşteride bir veya daha fazla etkin kampanya bulunur.
Her kampanyada, reklamlarınızı mantıklı koleksiyonlar halinde gruplandırmak için kullanılan bir veya daha fazla reklam grubu bulunur.
Reklam grubu reklamı, bir reklam grubunda yayınladığınız reklamı temsil eder. Reklam grubu başına yalnızca bir reklam grubu reklamı içerebilen uygulama kampanyaları hariç olmak üzere, her reklam grubu bir veya daha fazla reklam grubu reklamı içerir.
Maksimum Performans kampanyaları, diğer kampanya türlerinden farklı bir yapı kullanır: Maksimum Performans kampanyalarında reklam grupları ve reklam grubu reklamları yerine öğe grupları bulunur. AssetGroupAsset kullanarak reklam öğelerini bir öğe grubuna bağlar ve AssetGroupSignal kullanarak kitle veya arama teması sinyalleri eklersiniz.
Bir reklam grubuna veya kampanyaya bir ya da daha fazla AdGroupCriterion veya CampaignCriterion kaynağı ekleyebilirsiniz. Bunlar, reklamların nasıl tetikleneceğini tanımlayan ölçütleri gösterir.
Anahtar kelimeler, yaş grupları ve konumlar gibi birçok ölçüt türü vardır. Kampanya düzeyinde tanımlanan ölçütler, kampanyadaki diğer tüm kaynakları etkiler. Ayrıca AdGroupAd.start_date_time ve AdGroupAd.end_date_time kullanarak kampanyalar veya tek reklamlar için bütçelerin yanı sıra başlangıç ve bitiş tarihlerini ve saatlerini de belirtebilirsiniz.
Son olarak, öğeleri hesap, kampanya, reklam grubu veya öğe grubu düzeyinde ekleyebilirsiniz. Öğeler, reklamlarınıza telefon numaraları, açık adresler veya promosyonlar gibi ek bilgiler eklemenize olanak tanır. Öğelere genel bakış başlıklı makaleyi inceleyin.
Kaynaklar
Kaynaklar, Google Ads hesabınızdaki varlıkları temsil eder.
Campaign ve AdGroup, kaynaklara iki örnektir.
Nesne kimlikleri
Google Ads'deki her nesne kendi kimliğiyle tanımlanır. Bu kimliklerden bazıları tüm Google Ads hesaplarında benzersizken diğerleri yalnızca sınırlı bir kapsamda benzersizdir.
| Nesne kimliği | Benzersizlik kapsamı | Genel olarak benzersiz mi? |
|---|---|---|
| Bütçe Kimliği | Global | Evet |
| Kampanya Kimliği | Global | Evet |
| Reklam Grubu Kimliği | Global | Evet |
| Reklam Kimliği | Reklam grubu | Hayır, ancak (AdGroupId, AdId) çifti dünya genelinde benzersizdir. Bir AdId öğesinin birden fazla reklam grubuyla paylaşılması yasaktır. |
| AdGroupCriterion ID | Reklam grubu | Hayır, ancak (AdGroupId, CriterionId) çifti genel olarak benzersizdir. |
| CampaignCriterion ID | Kampanya | Hayır, ancak (CampaignId, CriterionId) çifti dünya genelinde benzersizdir |
| Etiket Kimliği | Müşteri | Hayır, ancak (CustomerId, LabelId) çifti dünya genelinde benzersizdir |
| UserList ID | Global | Evet |
| Öğe Kimliği | Global | Evet |
Bu kimlik kuralları, Google Ads nesneleriniz için yerel depolama alanı tasarlarken yararlı olabilir.
Bazı nesneler birden fazla öğe türü için kullanılabilir. Bu gibi durumlarda nesne, içeriğini açıklayan bir type alanı içerir. Örneğin, AdGroupAd, duyarlı arama ağı reklamı, otel reklamı veya Talep Yaratma reklamı gibi bir nesneyi ifade edebilir. Bu değere AdGroupAd.ad.type alanı üzerinden erişilebilir ve AdType enum'unda bir değer döndürülür. Değişkenliğin sürüme göre değişebileceğini unutmayın (örneğin, Ad üzerindeki VideoResponsiveAdInfo, v24 ve sonraki sürümlerde değişkendir).
Kaynak adları
Her kaynak, kaynağı ve üst öğelerini bir yolda birleştiren bir resource_name dizesiyle benzersiz şekilde tanımlanır. Örneğin, kampanya kaynak adları şu biçimdedir:
customers/customer_id/campaigns/campaign_id
Bu nedenle, müşteri kimliği 1234567 olan Google Ads hesabındaki kimliği 987654 olan bir kampanya için resource_name şu şekilde olur:
customers/1234567/campaigns/987654
Hizmetler
Hizmetler, Google Ads öğelerinizi almanıza ve değiştirmenize olanak tanır. Üç tür hizmet vardır: değiştirme, nesne ve istatistik alma ve meta veri alma hizmetleri.
Nesneleri değiştirme (mutasyona uğratma)
Kaynağa özgü hizmetler, mutate isteği kullanarak ilişkili bir kaynak türünün örneklerini değiştirir. Tek bir istekte birden fazla kaynak türü arasında atomik mutasyonlar gerçekleştirmek için (ör. kampanya bütçesi, kampanya ve reklam grubunu birlikte oluşturma) GoogleAdsService.Mutate yöntemini de kullanabilirsiniz.
Kaynaklara özel hizmet örnekleri:
Müşterileri değiştirmek için
CustomerService.Kampanyaları değiştirmek için
CampaignService.Reklam gruplarını değiştirmek için
AdGroupService.
Her mutate isteği, ilgili operation nesnelerini içermelidir. Örneğin, CampaignService.MutateCampaigns yöntemi bir veya daha fazla CampaignOperation örneği bekler. İşlemlerle ilgili ayrıntılı bilgi için Nesneleri değiştirme bölümüne bakın.
Eşzamanlı mutasyonlar
Bir Google Ads nesnesi aynı anda birden fazla kaynak tarafından değiştirilemez. Bu durum, uygulamanızla aynı nesneyi güncelleyen birden fazla kullanıcı varsa veya birden fazla iş parçacığı kullanarak Google Ads nesnelerini paralel olarak değiştiriyorsanız hatalara neden olabilir. Buna, aynı uygulamadaki birden fazla iş parçacığından veya farklı uygulamalardan (ör. uygulamanız ve eşzamanlı bir Google Ads kullanıcı arayüzü oturumu) nesnenin güncellenmesi dahildir.
API, güncellemeden önce bir nesneyi kilitleme yöntemi sunmaz. İki kaynak aynı anda bir nesneyi değiştirmeye çalışırsa API, DatabaseError.CONCURRENT_MODIFICATION_ERROR hatası verir.
Eşzamansız ve eşzamanlı mutasyonlar
Google Ads API mutate yöntemleri eşzamanlıdır. API çağrıları yalnızca nesneler değiştirildikten sonra yanıt döndürür. Bu nedenle, her istek için bir yanıt beklemeniz gerekir. Bu yaklaşımın kodlanması nispeten kolay olsa da yük dengelemeyi olumsuz etkileyebilir ve işlemler çağrıların tamamlanmasını beklemek zorunda kalırsa kaynakları boşa harcayabilir.
Alternatif bir yaklaşım, BatchJobService kullanarak nesneleri eşzamansız olarak değiştirmektir. Bu yöntem, işlemlerin tamamlanmasını beklemeden birden fazla hizmette toplu işlemler gerçekleştirir. Bir toplu iş gönderildikten sonra Google Ads API sunucuları işlemleri eşzamansız olarak yürütür ve diğer işlemleri gerçekleştirmek için süreçleri serbest bırakır. İşin tamamlanıp tamamlanmadığını
periyodik olarak kontrol edebilirsiniz.
Eşzamansız işleme hakkında daha fazla bilgi için Toplu işleme kılavuzuna bakın.
Değişiklik doğrulaması
Çoğu değişiklik isteği, çağrı gerçek veriler üzerinde yürütülmeden doğrulanabilir. İşlemi gerçekten yürütmeden eksik parametreler ve yanlış alan değerleri için isteği test edebilirsiniz.
Bu özelliği kullanmak için isteğin isteğe bağlı validate_only boole alanını true olarak ayarlayın. İstek, yürütülecekmiş gibi tamamen doğrulanır ancak son yürütme atlanır. Hata bulunmazsa yanıt, değiştirilmiş sonuçlar doldurulmadan (results boş) döndürülür. Doğrulama başarısız olursa istek varsayılan olarak GoogleAdsFailure RPC hatasıyla (partial_failure = false) başarısız olur veya partial_failure = true olduğunda partial_failure_error içinde işleme özgü hatalar içeren normal bir yanıt döndürür.
validate_only, yaygın politika ihlallerine yönelik reklamları test etmek için özellikle yararlıdır. Belirli kelimeler, noktalama işaretleri, büyük harf kullanımı veya uzunluk gibi politikaları ihlal eden reklamlar otomatik olarak reddedilir. Tek bir sakıncalı reklam, tüm toplu işlemin başarısız olmasına neden olabilir. validate_only
İstek içinde yeni bir reklamı test etmek bu tür ihlalleri ortaya çıkarabilir. Bunu nasıl kullanacağınızı görmek için politika ihlali hatalarını işleme ile ilgili kod örneğine bakın.
Nesneleri ve performans istatistiklerini alma
GoogleAdsService, nesneleri ve performans istatistiklerini almak için kullanılan tek ve birleştirilmiş hizmettir.
GoogleAdsService için tüm Search ve SearchStream istekleri; sorgulanacak kaynağı, alınacak kaynak özelliklerini ve performans metriklerini, isteği filtrelemek için kullanılacak yüklemleri ve performans istatistiklerini daha ayrıntılı bir şekilde dökümlemek için kullanılacak segmentleri belirten bir sorgu gerektirir. Sorgu biçimi hakkında daha fazla bilgi için Google Ads Sorgu Dili kılavuzunu inceleyin.
Meta verileri alma
GoogleAdsFieldService, Google Ads API'deki kaynaklarla ilgili meta verileri (ör. bir kaynak için kullanılabilir özellikler ve veri türü) alır. Bu hizmeti sorgulamayla ilgili ayrıntılar için Kaynak meta verileri kılavuzuna bakın.
Bu hizmet, GoogleAdsService için sorgu oluşturmak üzere gereken bilgileri sağlar. Kolaylık sağlamak için GoogleAdsFieldService tarafından döndürülen bilgiler alanlar referans belgelerinde de mevcuttur.