Video: 2019 atölyesindeki Hizmetler ve Kaynaklar konulu konuşmaya göz atın
Bu kılavuzda, Google Ads API'yi oluşturan temel bileşenler açıklanmaktadır. Google Ads API, kaynaklar ve hizmetlerden oluşur. Kaynak, Google Ads varlığını temsil ederken hizmetler ise Google Ads varlıklarını alıp değiştirir.
Nesne hiyerarşisi
Google Ads hesabı, bir nesne hiyerarşisi olarak görüntülenebilir.
Bir hesabın en üst düzey kaynağı müşteridir.
Her müşterinin bir veya daha fazla etkin kampanyası vardır.
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ı alabilen 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 bütçeler ve tarihler de belirtebilirsiniz.
Son olarak, hesap, kampanya veya reklam grubu düzeyinde uzantılar ekleyebilirsiniz. Uzantılar, reklamlarınızda telefon numarası, açık adres veya promosyonlar gibi ek bilgiler sağlamanıza olanak tanır.
Kaynaklar
Kaynaklar, Google Ads hesabınızdaki varlıkları temsil eder. Campaign
ve AdGroup
, kaynaklara örnek olarak verilebilir.
Nesne Kimlikleri
Google Ads'deki her nesne kendi kimliğiyle tanımlanır. Bu kimliklerin bazıları tüm Google Ads hesaplarında genel olarak benzersizdir. Bazıları ise yalnızca sınırlı bir kapsam dahilinde benzersizdir.
Nesne kimliği | Benzersizlik Kapsamı | Dünya Genelinde Benzersiz mi? |
---|---|---|
Bütçe Kimliği | Küresel | Evet |
Kampanya Kimliği | Küresel | Evet |
Reklam Grubu Kimliği | Küresel | Evet |
Reklam Kimliği | Reklam Grubu | Hayır, ancak (AdGroupId , AdId ) çifti genel olarak benzersiz |
AdGroupCriterion Kimliği | Reklam Grubu | Hayır, ancak (AdGroupId , CriterionId ) çifti genel olarak benzersiz |
Kampanya Ölçütü Kimliği | Kampanya | Hayır, ancak (CampaignId , CriterionId ) çifti genel olarak benzersiz |
Reklam Uzantıları | Kampanya | Hayır, ancak (CampaignId , AdExtensionId ) çifti genel olarak benzersiz |
Özet akışı kimliği | Küresel | Evet |
Özet Akışı Öğesi Kimliği | Küresel | Evet |
Feed Özellik Kimliği | Feed | Hayır |
Özet Akışı Eşleme Kimliği | Küresel | Evet |
Etiket Kimliği | Küresel | Evet |
Kullanıcı Listesi Kimliği | Küresel | Evet |
Bu kimlik kuralları, Google Ads nesneleriniz için yerel depolama alanı tasarlarken yararlı 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ından erişilebilir ve AdType
sıralaması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 şekildedir:
customers/customer_id/campaigns/campaign_id
Yani, 1234567
müşteri kimliğine sahip Google Ads hesabında 987654
kimliğine sahip bir kampanya için resource_name
şöyle 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
Bu hizmetler, mutate
isteği kullanarak ilişkili bir kaynak türünün örneklerini değiştirir. Ayrıca, tek bir kaynak örneği alan get
isteği de sağlarlar. Bu, 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
CampaignService
.Reklam gruplarını değiştirmek için
AdGroupService
.
Her mutate
isteği, karşılık gelen operation
nesneleri içermelidir. Örneğin, CampaignService.MutateCampaigns
yöntemi bir veya daha fazla CampaignOperation
örneğini bekler. İşlemlerin ayrıntılı bir açıklaması için Nesneleri Değiştirme ve İnceleme bölümüne bakın.
Eşzamanlı değişimler
Bir Google Ads nesnesi, birden fazla kaynak tarafından aynı anda değiştirilemez. Bu durum, uygulamanızla aynı nesneyi güncelleyen birden fazla kullanıcı varsa veya Google Ads nesnelerini birden fazla iş parçacığı kullanarak paralel olarak değiştiriyorsanız hatalar ortaya çıkabilir. Buna, nesnenin aynı uygulamadaki birden çok iş parçacığından 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 kilitlemenin bir yolunu 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şimler
Google Ads API değişim yöntemleri eşzamanlıdır. API çağrıları yalnızca nesneler dönüştürüldükten sonra yanıt döndürür. Bu da her isteğe yanıt için beklemenizi gerektirir. Bu yaklaşım, kodlama açısından nispeten basit olsa da süreçler çağrıların tamamlanmasını beklemeye zorlanırsa yük dengelemeyi ve kaynak israfını olumsuz yönde etkileyebilir.
Alternatif bir yaklaşım da BatchJobService
kullanarak nesneleri eşzamansız olarak değiştirmektir. Bu araç, işlemlerin tamamlanmasını beklemeden birden fazla hizmet üzerinde toplu işlemler gerçekleştirir. Bir toplu iş gönderildikten sonra, Google Ads API sunucuları işlemleri eşzamansız olarak yürüterek süreçlerin başka işlemler yapmasına olanak tanır. Düzenli olarak iş durumunu
tamamlanmış olup olmadığını kontrol edebilirsiniz.
Eşzamansız işleme hakkında daha fazla bilgi için Toplu İşleme kılavuzuna bakın.
Doğrulamayı değiştirme
Çoğu değişiklik isteği, çağrıyı gerçek verilere göre yürütmeden doğrulanabilir. İşlemi yürütmeden eksik parametreler ve yanlış alan değerleri açısından 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. Daha sonra istek, yürütülecekmiş gibi tamamen doğrulanır ancak nihai 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ı belirtir.
validate_only
, özellikle reklamları yaygın politika ihlalleri için test etme konusunda faydalıdır. Belirli kelimeler, noktalama işaretleri, büyük harf kullanımı veya uzunluklar gibi politikaları ihlal eden reklamlar otomatik olarak reddedilir. Tek bir sakıncalı reklam
tüm paketin başarısız olmasına neden olabilir. Yeni bir reklamı validate_only
isteğiyle test ederek
bu tür ihlalleri tespit edebilirsiniz. Bunu uygulamalı olarak görmek için politika ihlali hatalarını işleme ile ilgili kod örneğine bakın.
Nesneleri ve performans istatistiklerini alın
GoogleAdsService
, nesneleri ve performans istatistiklerini almak için kullanılan tek ve birleştirilmiş bir hizmettir.
GoogleAdsService
için tüm Search
ve SearchStream
isteklerinde sorgulanacak kaynağı, alınacak kaynak özellikleri ile performans metriklerini, isteği filtrelemek için kullanılacak tahminleri ve performans istatistiklerini daha ayrıntılı bir ş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ılavuzuna göz atın.
Meta veri alma
GoogleAdsFieldService
, Google Ads API'deki kaynaklarla ilgili meta verileri (ör. bir kaynağın kullanılabilir özellikleri ve veri türü) alır.
Bu hizmet, GoogleAdsService
öğesine sorgu oluşturmak için gereken bilgileri sağlar. Kolaylık sağlaması açısından GoogleAdsFieldService
tarafından döndürülen bilgiler, alan referans belgelerinde de yer almaktadır.