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ülebilir.
Bir hesabın en üst düzey kaynağı customer'dır.
Her müşteride bir veya daha fazla etkin kampanya bulunur.
Her kampanya, reklamlarınızı mantıksal koleksiyonlar halinde gruplandırmak için kullanılan bir veya daha fazla reklam grubu içerir.
Reklam grubu reklamı, yayınladığınız bir 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.
Bir reklam grubuna veya kampanyaya bir veya daha fazla AdGroupCriterion
ya da CampaignCriterion ekleyebilirsiniz. Bunlar, reklamların nasıl tetikleneceğini tanımlayan ölçütleri temsil eder.
Anahtar kelimeler, yaş aralıkları 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. Kampanya genelinde bütçeler ve tarihler de belirtebilirsiniz.
Son olarak, uzantıları hesap, kampanya veya reklam grubu düzeyinde ekleyebilirsiniz. Uzantılar, reklamlarınıza telefon numarası, açık adres veya promosyonlar gibi ek bilgiler eklemenize olanak tanır.
Kaynaklar
Kaynaklar, Google Ads hesabınızdaki öğeleri 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 genel olarak benzersizken bazıları yalnızca sınırlı bir kapsamda benzersizdir.
| Nesne kimliği | Benzersizliğin 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 genel olarak benzersizdir. |
| ReklamGrubuÖlçütü Kimliği | Reklam Grubu | Hayır, ancak (AdGroupId, CriterionId) çifti genel olarak benzersizdir. |
| CampaignCriterion ID | Kampanya | Hayır, ancak (CampaignId, CriterionId) çifti genel olarak benzersizdir. |
| Reklam Uzantıları | Kampanya | Hayır, ancak (CampaignId, AdExtensionId) çifti genel olarak benzersizdir. |
| Etiket Kimliği | Global | Evet |
| UserList ID | Global | Evet |
| Öğe Kimliği | Global | Evet |
Bu kimlik kuralları, Google Ads nesneleriniz için yerel depolama alanı tasarlarken faydalı 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 bir metin reklam, otel reklamı veya yerel reklam gibi bir nesneyi ifade edebilir. Bu değere AdGroupAd.ad.type alanı üzerinden erişilebilir ve AdType enum'ında bir değer döndürür.
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 (mutasyon)
Bu hizmetler, mutate isteğini kullanarak ilişkili bir kaynak türünün örneklerini değiştirir. Ayrıca, bir kaynağın yapısını incelemek için yararlı olabilecek tek bir kaynak örneğini alan bir get isteği de sağlarlar.
Hizmet örnekleri:
Müşterileri değiştirme için
CustomerService.CampaignServicekampanyaları değiştirmek için kullanılır.AdGroupService, reklam gruplarını değiştirmek için kullanılır.
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 ve İnceleme başlıklı makaleyi inceleyin.
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ınız varsa veya birden fazla iş parçacığı kullanarak Google Ads nesnelerini paralel olarak değiştiriyorsanız hatalara neden olabilir. 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 buna dahildir.
API, güncellemeden önce bir nesneyi kilitleme yöntemi sağlamaz. İki kaynak aynı anda bir nesneyi değiştirmeye çalışırsa API bir DatabaseError.CONCURRENT_MODIFICATION_ERROR oluşturur.
Eşzamansız ve eşzamanlı değişiklikler
Google Ads API değiştirme 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 yanıt beklemeniz gerekir. Bu yaklaşımın kodlanması nispeten kolay olsa da işlemlerin çağrıların tamamlanmasını beklemesi durumunda yük dengeleme olumsuz etkilenebilir ve kaynaklar boşa harcanabilir.
Alternatif bir yaklaşım, BatchJobService kullanarak nesneleri eşzamansız olarak değiştirmektir. Bu yaklaşım, tamamlanmaları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. Tamamlanma durumu için iş durumunu düzenli olarak kontrol edebilirsiniz.
Asenkron işleme hakkında daha fazla bilgi için Toplu İşleme Kılavuzu'na bakın.
Doğrulamayı değiştirme
Çoğu değiştirme isteği, gerçek verilerle çağrı 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. Bu durumda istek, yürütülecekmiş gibi tamamen doğrulanır ancak son yürütme atlanır. Hata bulunmazsa boş bir yanıt döndürülür. Doğrulama başarısız olursa yanıttaki hata mesajları, başarısızlık noktalarını gösterir.
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 kötü reklam, tüm toplu işlemin başarısız olmasına neden olabilir. validate_only
isteği içinde yeni bir reklamı test etmek bu tür ihlalleri ortaya çıkarabilir. Bunu uygulamada 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ı olarak incelemek 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ılabilen özellikler ve veri türü) alır.
Bu hizmet, GoogleAdsService sorgusu oluşturmak için gereken bilgileri sağlar. Kolaylık olması için, GoogleAdsFieldService tarafından döndürülen bilgiler alan referans belgelerinde de mevcuttur.