Google Ads Sorgu Dili

İpucu: GAQL sorgularınızı oluşturmak ve doğrulamak için Etkileşimli Sorgu Oluşturucu'yu kullanın.

Temel terminoloji

Kaynak

Google Ads'deki campaign veya ad_group gibi bir öğe.

Segment

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

Metrik

metrics.impressions veya metrics.clicks gibi bir performans ölçümü.

İlişkilendirilen Kaynak

FROM yan tümcesinde ana kaynağa dolaylı olarak katılan ve özelliklerini ana kaynak özellikleriyle birlikte seçmenize olanak tanıyan bir kaynak.

Kaynak veya meta veri bilgileri için sorgu

Google Ads Sorgu Dili, aşağıdaki bilgi türleri için Google Ads API'yi sorgulayabilir:

• GoogleAdsService Search veya SearchStream kullanan kaynaklar ve bunlarla ilgili ö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 çifti için ek bir satır da gösterilir.

• GoogleAdsFieldService'daki kullanılabilir alanlar ve kaynaklar hakkında meta veriler: Bu hizmet, uyumlulukları ve türleriyle ilgili ayrıntıları içeren sorgulanabilir alanların bir kataloğunu sunar.

  GoogleAdsFieldService sorgusunun sonucu, her biri istenen alanla ilgili ayrıntıları içeren GoogleAdsField örneklerinin bir listesidir.GoogleAdsField

Sorgu yapısı hakkında daha fazla bilgi için Sorgu yapısı ve Google Ads Sorgu Dili dil bilgisi bölümlerine bakın.

Kaynak özelliklerini sorgulama

Aşağıda, kampanya kaynağının özellikleriyle ilgili temel bir sorgu örneği verilmiştir. Bu örnekte kampanya kimliği, adı 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 değeri de dahil olmak üzere seçilen alanlarla doldurulmuş bir campaign nesnesini temsil eder.

Kampanya sorguları için başka hangi alanların kullanılabildiğini öğrenmek istiyorsanız Campaign referans belgelerine bakın.

Metrikleri sorgulama

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 durumu PAUSED olan ve 1.000'den fazla gösterim alan kampanyaları filtreler ve kampanya kimliğine göre sıralar. Sonuçta elde edilen her GoogleAdsRow, seçilen metriklerle doldurulmuş bir metrics alanına sahip olur.

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

Segmentleri sorgulama

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

Metrikleri sorgulamaya 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, her bir GoogleAdsRow sonucunun bir kampanya ve tarih segmenti grubunu temsil etmesine neden olur. Segmentasyon, seçilen metrikleri bölerek SELECT ifadesindeki her segmente göre gruplandırır.

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

İlgili kaynakların özelliklerini sorgulama

Belirli bir kaynak için yapılan sorguda, varsa diğer ilgili kaynaklarla birleştirme yapabilirsiniz. Bu ilgili kaynaklar "ilişkilendirilen kaynaklar" olarak bilinir. Sorgunuzda bir özellik seçerek ilişkilendirilmiş kaynaklarla dolaylı olarak birleştirme 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 alır. Elde edilen 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.
• Geliştirme ve test sırasında büyük sonuç kümelerini işlememek için LIMIT kullanın.
• Veri aktarımını ve yanıt boyutunu en aza indirmek için WHERE ifadesinde filtreler uygulayın.
• Karmaşık sorgular oluşturmadan önce alan uyumluluğunu ve veri türlerini kontrol etmek için GoogleAdsFieldService kullanın.
• Bazı alanların, özellikle de büyük miktarda veri veya karmaşık hesaplamalar içeren alanların sorgu maliyetini artırabileceğini unutmayın.

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

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

1. Gösterim sayısı 1.000'den fazla olan tüm PAUSED kampanyaları için bir sorgu yürütün.
2. Yanıttaki her GoogleAdsRow öğesinin campaign alanından Campaign nesnesini alın.
3. Her bir kampanyanın durumunu PAUSED yerine ENABLED olarak değiştirin.
4. Değiştirilen kampanyaları ve ilgili FieldMask değerini güncellemek için CampaignService.MutateCampaigns yöntemini çağırın.

Not: Bir sorgudan alınan kaynakları güncellerken FieldMask belirtin (veya istemci kitaplığınızın yerleşik alan maskesi yardımcı programını kullanın). Böylece yalnızca değiştirilen alanlar güncellenir ve READ_ONLY_FIELD ya da IMMUTABLE_FIELD hataları veya diğer özelliklerin yanlışlıkla üzerine yazılması önlenir.

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 bir sorguyu doğrulamak veya oluşturmak için gereken meta verileri sağladığı için geliştiriciler bu işlemi programatik olarak yapabilir. Meta veriler için tipik bir sorgu şu şekildedir:

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

Bu sorgudaki <INSERT_RESOURCE_OR_FIELD> ifadesini bir kaynakla (ör. customer veya campaign) ya da alanla (ör. campaign.id, metrics.impressions veya ad_group.id) değiştirebilirsiniz.

Önemli nokta: Bu sorguda FROM ifadesinin bulunmadığına dikkat edin.

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

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

Google Ads Sorgu Dili söz dizimi, yan tümceleri ve operatörleri desteklenen tüm Google Ads API sürümlerinde (v23, v24, v25 ve v26) aynı olsa da sorgulanabilir kaynaklar, segmentler, metrikler ve raporlama davranışları kataloğu ana sürüme göre farklılık gösterir. Hedef API sürümü uç noktasında GoogleAdsFieldService sorgusu yaparak ilgili sürümün alanlarını ve uyumluluk kurallarını inceleyin:

• Nihai URL genişletmesi öğe görünümü:
  • Alışveriş kampanyası desteği (sürüm 26 ve sonraki sürümler): final_url_expansion_asset_view, Maksimum Performans ve Arama Ağı kampanyalarının yanı sıra Alışveriş kampanyalarını (campaign.advertising_channel_type = 'SHOPPING') destekler. Alışveriş kampanyaları için ad_group alanlarını seçip bunlara göre filtreleme yapabilirsiniz ancak asset_group alanlarını seçemezsiniz.
  • Seçilebilir metrikler (v25 ve sonraki sürümler): final_url_expansion_asset_view sorgusu, görünüm için seçilebilir tüm metrikleri döndürür. Sürüm 24 ve önceki sürümlerde, yanıtlarda Maksimum Performans kampanyaları için yalnızca metrics.conversions ve metrics.conversions_value, Arama Ağı kampanyaları için ise metrics.impressions yer alır.
• Yaşam döngüsü hedefi kaynakları: v25 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 (v24 ve önceki sürümlerde yeni müşteri edinme hedefleri için goal ve campaign_goal_config ile birlikte müşteri elde tutma hedefleri için kullanılıyordu) yerini alır.
• Uygulama kampanyaları için Alışveriş ürün raporlaması: 24. sürüm 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 (23. sürümde, uygulama kampanyaları shopping_product sonuçlarından hariç tutulur).
• Sürüme özel kaynaklar, segmentler ve metrikler:
  • v26 ve sonraki sürümler: search_lift_keyword_bundle kaynağını, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property ve Arama Artışı metriklerini (ör. metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros ve metrics.search_lift_impressions) içerir.
  • 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ğını, shopping_performance_view üzerinde segments.conversion_attribution_event_type, segments.mobile_device_platform ve performance_max_placement_view üzerinde segments.ad_network_type'yi içerir. campaign.video_brand_safety_suitability (customer.video_brand_safety_suitability ile değiştirildi), campaign_budget sürümündeki segments.ad_sub_network_type ve ad_group_asset, campaign_asset ve customer_asset sürümlerindeki segments.click_type (yalnızca 23. sürümde seçilebilir) kaldırıldı.
• Ayrıntılı tarih yeniden inceleme hata kodu: 37 aylık yeniden inceleme aralığının ötesinde segments.date, segments.week veya segments.hour ölçütüne göre segmentlere ayıran (ya da bir aylık alt tarih aralığına göre filtreleyen) sorgular, 24. sürüm ve sonraki sürümlerde DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (veya 23. sürümde DateRangeError.UNKNOWN) döndürür. Ayrıntılar için Tarih aralıkları bölümüne bakın.

Kod örnekleri

İstemci kitaplıklarında, GoogleAdsService dilinde Google Ads Sorgu Dili'nin kullanımına dair örnekler bulunur. Temel işlemler klasöründe GetCampaigns, GetKeywords ve SearchForGoogleAdsFields gibi örnekler bulunur.