API Yapısı

. 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. İlgili içeriği oluşturmak için kullanılan Google Ads API, kaynaklar ve hizmetlerden oluşur. Kaynak, Google Ads'i temsil eder varlık gösterirken, hizmetler Google Ads varlıklarını alıp manipüle eder.

Nesne hiyerarşisi

Google Ads hesabı, bir nesne hiyerarşisi olarak görüntülenebilir.

Kampanya modeli

  • Bir hesabın en üst düzey kaynağı Müşteri.

  • Her müşteri bir veya daha fazla etkin kampanyalar.

  • Her kampanya bir veya daha fazla reklam grubu içerir. mantıksal koleksiyonlar halinde gruplandırabilirsiniz.

  • Reklam grubu reklamı ziyaret etmekte olduğunuz bir reklamı çalışıyor. Reklam başına yalnızca bir reklam grubu reklamı bulunabilen uygulama kampanyaları hariç grubunda, her reklam grubunda bir veya daha fazla reklam grubu reklamı bulunur.

Bir veya daha fazla AdGroupCriterion ekleyebilirsiniz veya CampaignCriterion adresini bir reklam grubuna ekleyin veya pek de iyi olmadığını unutmayın. Bunlar, reklamların nasıl tetiklendiğini tanımlayan ölçütleri temsil eder.

Birçok ölçüt türü vardır. anahtar kelimeler, yaş aralıkları ve konumlar gibi). Kampanyada tanımlanan ölçütler düzeyindeki sonuçlar, kampanyadaki diğer tüm kaynakları etkiler. Ayrıca aşağıdakileri de belirtebilirsiniz: kampanya genelinde bütçeleri ve tarihleri kontrol edebilir.

Son olarak, uzantıları hesap, kampanya veya reklam grubu düzeyi. Uzantılar, farklı web siteleri için bilgiler (ör. telefon numarası, açık adres veya tanıtımlar)

Kaynaklar

Kaynaklar, Google Ads hesabınızdaki varlıkları temsil eder. Campaign ve AdGroup iki örnektir mevcut.

Nesne Kimlikleri

Google Ads'deki her nesne kendi kimliğiyle tanımlanır. Bu kimliklerden bazıları Tüm Google Ads hesaplarında global olarak benzersizken bazıları yalnızca olduğunu görebiliriz.

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 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 Global Evet
Özet Akışı Öğesi Kimliği Global Evet
Feed Özellik Kimliği Feed Hayır
Özet Akışı Eşleme Kimliği Global Evet
Etiket Kimliği Global Evet
Kullanıcı Listesi Kimliği Global Evet

Bu kimlik kuralları, Google Ads hesabınız için yerel depolama alanını tasarlarken işinize yarayabilir nesneler'i tıklayın.

Bazı nesneler birden fazla varlık türü için kullanılabilir. Böyle durumlarda, nesne içeriğini açıklayan bir type alanı içerir. Örneğin, AdGroupAd, metin reklam gibi bir nesneye başvuruda bulunabilir. reklam veya yerel reklam olabilir. Bu değere, AdGroupAd.ad.type alanını kullanır ve AdType sıralaması.

Kaynak adları

Her kaynak bir resource_name dizesiyle benzersiz şekilde tanımlanır. kaynağı ve üst öğelerini bir yol şeklinde birleştirir. Örneğin, kampanya kaynak adları şu şekildedir:

customers/customer_id/campaigns/campaign_id

Dolayısıyla Google Ads hesabında, 987654 kimliğine sahip ve müşteri kimliğine sahip bir kampanya için 1234567, resource_name şöyle olur:

customers/1234567/campaigns/987654

Hizmetler

Hizmetler, Google Ads öğelerinizi almanıza ve değiştirmenize olanak tanır. Üç tür hizmetler: değiştirme, nesne ve istatistik alma ve meta veri alma kullanıma sunuyoruz.

Nesneleri değiştirme

Bu hizmetler, mutate kullanarak ilişkili bir kaynak türünün örneklerini değiştirir isteğinde bulunabilirsiniz. Ayrıca, tek bir kaynak alan bir get isteği de sağlarlar. Bu örnek, bir kaynağın yapısını incelemek için yararlı olabilir.

Hizmet örnekleri:

Her mutate isteği, karşılık gelen operation nesneleri içermelidir. Örneğin, Örneğin, CampaignService.MutateCampaigns yöntemi bir veya daha fazla değer bekler CampaignOperation örnekleri. Görüntüleyin Nesneleri Değiştirme ve İnceleme detaylıca değineceğiz.

Eşzamanlı değişimler

Bir Google Ads nesnesi, birden fazla kaynak tarafından aynı anda değiştirilemez. Bu aynı nesneyi güncelleyen birden fazla kullanıcınız olduğunda hata oluşabilir veya birden çok reklam öğesi kullanarak Google Ads nesnelerini buna paralel olarak değiştiriyorsanız ileti dizileri. Buna, aynı veya farklı uygulamalardan (örneğin, uygulamanızın aynı anda gerçekleşen Google Ads kullanıcı arayüzü oturumu).

API, bir nesneyi güncellemeden önce kilitlemenin bir yolunu sağlamaz; iki kaynak bir nesneyi aynı anda dönüştürmeye çalışırsanız API, DatabaseError.CONCURRENT_MODIFICATION_ERROR.

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 yanıt döndürür sonra nesneler mutabakata tabidir; her bir davranış için isteğinde bulunabilirsiniz. Bu yaklaşım, kodlama açısından nispeten basit olsa da süreçlerin zorunlu kılınması durumunda yük dengelemeyi ve kaynakların israfını olumsuz etkiler. aramaların tamamlanmasını bekleyin.

Alternatif bir yaklaşım da BatchJobService, birden fazla hizmet üzerinde işlem yapılmasını sağlar. Bir toplu iş gönderildiğinde, Google Ads API sunucuları işlemleri eşzamansız olarak yürütür, işlemleri gerçekleştirebilmek için süreçleri serbest bırakır. Belirli aralıklarla takip etmeniz gerekir.

Daha fazla bilgi için Toplu İşleme kılavuzuna bakın eşzamansız işleme.

Doğrulamayı değiştirme

Çoğu değişiklik isteği, çağrı fiilen yürütülmeden doğrulanabilir karşılaştırabilirsiniz. Eksik parametreler ve yanlış parametreler ile ilgili isteği test edebilirsiniz. alan değerlerinin kullanılmasını öneririz.

Bu özelliği kullanmak için isteğin isteğe bağlı validate_only boole alanını şuna ayarlayın: true. Böylece istek, müzakere adımını yürütülür ancak son yürütme atlanır. Hata bulunmazsa boş bir hatası döndürülür. Doğrulama başarısız olursa yanıttaki hata mesajları ve hata noktalarını gösterir.

validate_only, özellikle genel politikaya yönelik reklamların test edilmesinde faydalıdır ihlal eder. Reklamlar şunun gibi politikaları ihlal ediyorsa otomatik olarak reddedilir: kelime, noktalama, büyük harf veya uzunluğa sahip olduğundan emin olun. Tek bir sakıncalı reklam tüm grubun başarısız olmasına neden olabilir. Yeni bir reklamı validate_only içinde test etme talebiniz bu tür ihlalleri ortaya çıkarabilir. Sevkiyata hazırlık için politika ihlali hatalarını inceleyin yardımcı olabilir.

Nesneleri ve performans istatistiklerini alın

GoogleAdsService tek ve birleştirilmiş performans istatistiklerini almaya yönelik bir hizmet.

GoogleAdsService için tüm Search ve SearchStream istekleri, kaynağı şu şekilde belirten bir sorgu gerektiriyor: alınacak kaynak özellikleri ve performans metrikleri, isteği filtrelemek için kullanılacak koşullar ve daha ileri düzeyde ve performans istatistiklerini ayırabiliriz. Sorgu biçimi hakkında daha fazla bilgi için Google Ads Sorgu Dili kılavuzunu inceleyin.

Meta veri alma

GoogleAdsFieldService alır Google Ads API'deki kaynaklarla ilgili meta veriler (örneğin, bir ve veri türünü içerir.

Bu hizmet, API'yi kullanarak sorgu oluşturma işleminde GoogleAdsService. Kolaylık sağlaması açısından tarafından döndürülen bilgiler GoogleAdsFieldService da mevcut inceleyebilirsiniz.

Önceki
Genel bakış
Sonraki
Varlık ilişkileri