Video: 2019 atölyesindeki Hizmetler ve Kaynaklar konulu konuşmaya göz atın
Bu kılavuzda, Google Ads API'yi oluşturan birincil bileşenler tanıtılmaktadır. Google Ads API, kaynaklardan ve hizmetlerden oluşur. Kaynaklar bir Google Ads öğesini temsil ederken hizmetler Google Ads öğelerini alır ve bunlar üzerinde işlem yapar.
Nesne hiyerarşisi
Google Ads hesabı, nesne hiyerarşisi olarak görülebilir.
Hesabın üst düzey kaynağı müşteridir.
Her müşteri bir veya daha fazla etkin kampanya içerir.
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ı olabilecek uygulama kampanyaları hariç 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 tetiklendiğ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 geçerli bütçeleri ve tarihleri de belirtebilirsiniz.
Son olarak, hesap, kampanya veya reklam grubu düzeyinde uzantılar 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 örnek gösterilebilir.
Nesne kimlikleri
Google Ads'deki her nesne kendi kimliğiyle tanımlanır. Bu kimliklerden bazıları tüm Google Ads hesaplarında dünya genelinde benzersizken bazıları yalnızca sınırlı bir kapsamda benzersizdir.
| Nesne kimliği | Benzersizlik kapsamı | Dünya genelinde 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 |
| AdGroupCriterion kimliği | Reklam Grubu | Hayır, ancak (AdGroupId, CriterionId) çifti dünya genelinde benzersizdir |
| CampaignCriterion kimliği | Kampanya | Hayır, ancak (CampaignId, CriterionId) çifti dünya genelinde benzersizdir |
| Reklam Uzantıları | Kampanya | Hayır, ancak (CampaignId, AdExtensionId) çifti dünya genelinde benzersizdir |
| Özet akışı kimliği | Global | Evet |
| Feed Öğe Kimliği | Global | Evet |
| Feed Özelliği Kimliği | Feed | Hayır |
| Feed eşleme kimliği | Global | Evet |
| Etiket Kimliği | Global | Evet |
| UserList kimliği | Global | Evet |
Bu kimlik kuralları, Google Ads nesneleriniz için yerel depolama alanı tasarlarken faydalı olabilir.
Bazı nesneler birden fazla varlık türü için kullanılabilir. Bu gibi durumlarda nesne, içeriğini açıklayan bir type alanı içerir. Örneğin, AdGroupAd 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 sınıfında bir değer döndürür.
Kaynak adları
Her kaynak, kaynağı ve üst öğelerini bir yola bağlayan bir resource_name dizesi ile benzersiz şekilde tanımlanır. Örneğin, kampanya kaynağı adları şu şekildedir:
customers/customer_id/campaigns/campaign_id
Dolayısıyla, müşteri kimliği 1234567 olan Google Ads hesabında 987654 kimlikli 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 (dönüştürme)
Bu hizmetler, ilişkili bir kaynak türünün örneklerini mutate isteğinde bulunarak değiştirir. Ayrıca, tek bir kaynak örneğini alan bir get isteği de sağlarlar. Bu istek, bir kaynağın yapısını incelemek için yararlı olabilir.
Hizmet örnekleri:
Müşterileri değiştirmek için
CustomerService.Kampanyaları değiştirmek için
CampaignServiceReklam 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ı bir tartışma için Nesneleri Değiştirme ve İnceleme başlıklı makaleyi inceleyin.
Eşzamanlı mutasyonlar
Bir Google Ads nesnesi birden fazla kaynak tarafından aynı anda değiştirilemez. Bu durum, uygulamanızla aynı nesneyi birden fazla kullanıcının güncellemesi veya Google Ads nesnelerini birden fazla iş parçacığı kullanarak paralel olarak değiştirmeniz durumunda hatalara neden olabilir. Buna, nesnenin aynı uygulamadaki birden fazla iş parçacığında veya farklı uygulamalardan (örneğin, uygulamanız ve eşzamanlı bir Google Ads kullanıcı arayüzü oturumu) güncellenmesi de dahildir.
API, bir nesneyi güncellemeden önce kilitleme yöntemi sunmaz. İ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ı mutasyonlar
Google Ads API'nin mutasyon yöntemleri senkronizedir. 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 süreçlerin çağrıların tamamlanmasını beklemek zorunda kalması, yük dengesini olumsuz yönde etkileyebilir ve kaynakların boşa harcanmasına neden olabilir.
Alternatif bir yaklaşım, BatchJobService kullanarak nesneleri eşzamansız olarak değiştirmek olabilir. Bu yöntem, birden fazla hizmette işlemlerin tamamlanmasını beklemeden 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 işlemleri diğer işlemleri gerçekleştirmek için serbest bırakır. Tamamlanma durumunu kontrol etmek 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.
Değişiklik doğrulaması
Çoğu değiştirme isteği, gerçek verilere karşı çağrıyı gerçekten yürütmeden doğrulanabilir. İşlemi gerçekten yürütmeden isteği eksik parametreler ve yanlış alan değerleri açısından test edebilirsiniz.
Bu özelliği kullanmak için isteğin isteğe bağlı validate_only boole alanını true olarak ayarlayın. Ardından 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ı, hata noktalarını gösterir.
validate_only, özellikle reklamları yaygın politika ihlalleri açısından test etmek için 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 grubun başarısız olmasına neden olabilir. Yeni bir reklamı validate_only isteğinde test etmek bu tür ihlalleri ortaya çıkarabilir. Bu işlemin nasıl yapıldığını görmek için politika ihlali hatalarını ele alma konulu kod örneğine bakın.
Nesneleri ve performans istatistiklerini alma
GoogleAdsService, nesneleri ve performans istatistiklerini almak için tek ve birleşik bir hizmettir.
GoogleAdsService için tüm Search ve SearchStream isteklerinde, sorgulanacak kaynağı, alınacak kaynak özelliklerini ve performans metriklerini, isteği filtrelemek için kullanılacak önermelerin yanı sıra performans istatistiklerini daha ayrıntılı şekilde incelemek için kullanılacak segmentleri belirten bir sorgu gerekir. 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 için sorgu oluşturmak için gereken bilgileri sağlar. Kolaylık olması için GoogleAdsFieldService tarafından döndürülen bilgilere alan referans dokümanlarından da ulaşabilirsiniz.