Google Ads Sorgu Dili

Temel terminoloji

Kaynak

Google Ads'deki bir varlık (ör. campaign veya ad_group).

Segment

Verileri gruplandırmak için kullanılan bir boyut (ör. segments.date veya segments.device). Segmentler, metriklerle birlikte SELECT ifadesine dahil edildiğinde metrikler segmente göre bölünür.

Metrik

Performans ölçümü (ör. metrics.impressions veya metrics.clicks).

İlişkilendirilen Kaynak

FROM Yan tümcesindeki ana kaynağa örtülü olarak katılan bir kaynak. Bu kaynak, ana kaynak özellikleriyle birlikte kendi özelliklerini de seçmenize olanak tanır.

Kaynak veya meta veri bilgileri için sorgu

Google Ads Sorgu Dili, Google Ads API'sinde aşağıdaki bilgi türleri için sorgu oluşturabilir:

• GoogleAdsService Search veya SearchStream kullanan kaynaklar ve bunlarla ilişkili özellikler, segmentler ve metrikler: GoogleAdsService sorgusunun sonucu, her biri GoogleAdsRow bir kaynağı temsil eden GoogleAdsRow örneklerinin listesidir.

  Herhangi bir özellik veya metrik istenirse satırda bu alanlar da yer alır. Herhangi bir segment istenirse yanıtta her segment-kaynak grubu için ek bir satır da gösterilir.

• GoogleAdsFieldService'daki kullanılabilir alanlar ve kaynaklarla ilgili meta veriler: Bu hizmet, sorgulanabilir alanların uyumluluğu ve türüyle ilgili ayrıntıları içeren bir katalog sunar.

  GoogleAdsFieldService sorgusunun sonucu, GoogleAdsField örneklerinin bir listesidir. Her GoogleAdsField, istenen alanla ilgili ayrıntıları içerir.

Sorgu yapısı hakkında daha ayrıntılı bilgi için Sorgu yapısı ve Google Ads Query Language grameri başlıklı makaleleri inceleyin.

Kaynak özelliklerini sorgulama

Kampanya kaynağının özellikleriyle ilgili temel bir sorgu örneğini aşağıda bulabilirsiniz. Bu örnekte, kampanya kimliğinin, adının ve durumunun nasıl döndürüleceği gösterilmektedir:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Bu sorgu, kampanya kimliğine göre sıralama yapar. Elde edilen her GoogleAdsRow, kampanyanın resource_name dahil olmak üzere seçilen alanlarla doldurulmuş bir campaign nesnesini temsil eder.

Kampanya sorgularında hangi alanların kullanılabildiğini öğrenmek için Campaign referans belgelerine bakın.

Metrikler için sorgu oluşturma

Belirli bir kaynak için seçilen özelliklerin yanı sıra ilgili metrikleri de sorgulayabilirsiniz:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Bu sorgu, yalnızca PAUSED durumuna sahip olan ve 1.000'den fazla gösterim alan kampanyaları filtrelerken kampanya kimliğine göre sıralama yapar. Elde edilen her GoogleAdsRow, seçilen metriklerle doldurulmuş bir metrics alanına sahip olur.

Sorgulanabilir metriklerin listesi için Metrics belgelerine bakın.

Segmentler için sorgu oluşturma

Belirli bir kaynak için seçilen özelliklerin yanı sıra ilgili segmentleri de sorgulayabilirsiniz:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

Metrikler için sorgu oluşturmaya benzer şekilde, bu sorgu yalnızca durumu PAUSED olan ve 1.000'den fazla gösterim alan kampanyaları filtreler. Ancak bu sorgu, verileri tarihe göre segmentlere ayırır. Bu durum, sonuçta elde edilen her bir GoogleAdsRow değerinin bir kampanya ve tarih segmenti demetini temsil etmesine neden olur. Segmentlere ayırma, seçilen metrikleri SELECT yan tümcesindeki her segmente göre gruplandırarak böler.

Sorgulanabilir segmentlerin listesi için Segments belgelerine bakın.

İlgili bir kaynağın özelliklerini sorgulama

Belirli bir kaynak için yapılan sorguda, varsa diğer ilgili kaynaklara karşı birleştirme işlemi yapabilirsiniz. Bu ilgili kaynaklar "atfedilen kaynaklar" olarak bilinir. Sorgunuzda bir özellik seçerek, ilişkilendirilmiş kaynaklara karşı örtülü olarak birleştirme işlemi yapabilirsiniz.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Bu sorgu yalnızca kampanya özelliklerini seçmekle kalmaz, aynı zamanda seçilen her kampanyadan ilgili özellikleri de getirir. Sonuçtaki her GoogleAdsRow, seçilen kampanya özelliklerinin yanı sıra seçilen teklif stratejisi özelliği bidding_strategy.name ile doldurulmuş bir campaign nesnesini temsil eder.

Kampanya sorguları için hangi ilişkilendirilmiş kaynakların kullanılabildiğini öğrenmek üzere Campaign referans belgelerine bakın.

En iyi uygulamalar

• Uzun yanıt sürelerini ve zaman aşımlarını önlemek için yalnızca ihtiyacınız olan alanları seçin.
• Büyük sonuç kümelerinin işlenmesini önlemek için geliştirme ve test sırasında LIMIT kullanın.
• Veri aktarımını ve yanıt boyutunu en aza indirmek için WHERE ifadesinde filtre uygulayın.
• Karmaşık sorgular oluşturmadan önce alan uyumluluğunu ve veri türlerini kontrol etmek için GoogleAdsFieldService simgesini kullanın.
• Bazı alanların, özellikle de büyük miktarda veri veya karmaşık hesaplamalar içerenlerin sorgu maliyetini artırabileceğini unutmayın.

Sorgu sonuçlarına göre değiştirme

Belirli bir kaynak için sorgu oluştururken döndürülen sonuçları hemen nesne olarak alabilir, bunları değiştirebilir ve söz konusu kaynağın hizmetindeki mutate yöntemine geri gönderebilirsiniz. Örnek bir iş akışı:

1. 1.000'den fazla gösterime sahip tüm PAUSED kampanyaları için bir sorgu yürütün.
2. Yanıtın campaign alanındaki her GoogleAdsRow öğesinden Campaign nesnesini alın.
3. Her kampanyanın durumunu PAUSED olarak ENABLED değiştirin.
4. Değiştirilen kampanyalar ve bunları güncellemek için ilgili bir CampaignService.MutateCampaigns ile FieldMask çağrısı yapın.

Alan meta verileri

GoogleAdsFieldService adresine gönderilen sorgular, alan meta verilerini almak için kullanılır. Bu bilgiler, alanların bir sorguda birlikte nasıl kullanılabileceğini anlamak için kullanılabilir. Veriler API'den alınabildiği ve sorgu doğrulamak veya oluşturmak için gerekli meta veriler sağlandığı için geliştiriciler bunu programatik olarak yapabilir. Meta veriler için tipik bir sorgu aşağıda verilmiştir:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Bu sorgudaki <INSERT_RESOURCE_OR_FIELD> yerine bir kaynak (ör. customer veya campaign) ya da alan (ör. campaign.id, metrics.impressions veya ad_group.id) koyabilirsiniz.

Sorgulanabilir alanların listesi için GoogleAdsField belgelerine bakın.

Sürüme özgü farklılıklar

Google Ads sorgu dili söz dizimi, ifadeleri ve operatörleri desteklenen tüm Google Ads API sürümlerinde (v23, v24 ve v25) aynı olsa da sorgulanabilir kaynaklar, segmentler, metrikler ve raporlama davranışları kataloğu ana sürüme göre farklılık gösterir. Alanları ve uyumluluk kurallarını incelemek için hedef API sürümü uç noktasında sorgu GoogleAdsFieldService gönderin:

• Yaşam döngüsü hedefi kaynakları: 25. sürüm ve sonraki sürümlerde tüm yaşam döngüsü hedefleri (yeni müşteri edinme, müşteri elde tutma ve bağlılık elde tutma) birleştirilmiş goal ve campaign_goal_config kaynaklarından sorgulanır. Bu kaynaklar, customer_lifecycle_goal ve campaign_lifecycle_goal kaynaklarının (24. sürüm ve önceki sürümlerde yeni müşteri edinme hedefleri için goal ve campaign_goal_config ile birlikte kullanılan) yerini alır.
• Nihai URL genişletme öğesi görüntüleme metrikleri: 25. sürüm ve sonraki sürümlerde final_url_expansion_asset_view sorgulandığında görüntüleme için seçilebilir tüm metrikler döndürülür. v24 ve önceki sürümlerde, yanıtlar yalnızca Maksimum Performans kampanyaları için metrics.conversions ve metrics.conversions_value, Arama Ağı kampanyaları için ise metrics.impressions değerlerini içerir.
• Uygulama kampanyaları için Alışveriş ürünü raporları: v24 ve sonraki sürümlerde, shopping_product kaynağı, Alışveriş, Maksimum Performans, Talep Yaratma ve video kampanyalarının yanı sıra uygulama kampanyaları için de ürün satırları döndürür (v23'te uygulama kampanyaları shopping_product sonuçlarının dışında tutulur).
• Sürüme özel kaynaklar, segmentler ve metrikler:
  • v25 ve sonraki sürümler: Artış ölçümü kaynaklarını (ör. lift_measurement_config), segments.ad_sub_format_type ve segments.loyalty_membership gibi segmentleri ve YouTube etkileşim metriklerini (metrics.youtube_likes, metrics.youtube_comments ve metrics.youtube_shares) içerir. local_services_lead.contact_details.email (v24 ve önceki sürümlerde seçilebilir) kaldırılır.
  • v24 ve sonraki sürümler: cart_data_sales_view kaynağı, shopping_performance_view üzerinde segments.conversion_attribution_event_type, performance_max_placement_view üzerinde segments.mobile_device_platform ve segments.ad_network_type özelliklerini içerir. campaign.video_brand_safety_suitability (customer.video_brand_safety_suitability ile değiştirildi), campaign_budget'deki segments.ad_sub_network_type ve ad_group_asset, campaign_asset ve customer_asset'deki segments.click_type (yalnızca v23'te seçilebilir) kaldırıldı.
• Ayrıntılı tarih yeniden inceleme aralığı hata kodu: 37 aylık yeniden inceleme aralığı penceresinin ötesinde segments.date, segments.week veya segments.hour'e göre segmentlere ayıran (ya da aylık bir tarih aralığına göre filtreleyen) sorgular, v24 ve sonraki sürümlerde DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (v23'te ise DateRangeError.UNKNOWN) döndürür. Ayrıntılar için Tarih aralıkları başlıklı makaleyi inceleyin.

Kod örnekleri

İstemci kitaplıklarında, GoogleAdsService içinde Google Ads Query Language'in kullanımına ilişkin örnekler bulunur. Temel işlemler klasöründe GetCampaigns, GetKeywords ve SearchForGoogleAdsFields gibi örnekler bulunur.