Sorgu Yapısı

Kaynak, segment ve metrik alanlarıyla ilgili sorgular GoogleAdsService Search veya SearchStream yöntemlerine gönderilebilir. Google Ads Sorgu Dili'nde bir sorgu oluşturmak için dil gramerini kullanarak sorguyu oluşturmanız gerekir. Sorgu, bir dizi yan tümceden oluşur:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Yan tümceler, doğru verileri seçmenize yardımcı olmak için alan adlarını, kaynak adlarını, operatörleri, koşulları ve sıralamaları kullanır. Tek bir sorguda birleştirildiğinde Google Ads API kullanılarak istekte bulunulabilir.

Maddeler

ondemand_video Video: GAQL Alan Uyumluluğu

SEÇ

SELECT ifadesi, istekte getirilecek bir alan grubunu belirtir. SELECT, virgülle ayrılmış kaynak alanları, segment alanları ve metrikler listesini alır ve yanıttaki değerleri döndürür. Sorguda SELECT ifadesi zorunludur.

Aşağıdaki örnek sorguda, belirli bir kaynak için özellik seçme örneği gösterilmektedir:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Tek bir istekte farklı alan türleri isteyebilirsiniz. Örneğin:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

• Kaynak alanları

  • campaign.id
  • campaign.name

• Kaynak alanları

  • bidding_strategy.id
  • bidding_strategy.name

• Segment alanları

  • segments.device
  • segments.date

• Metrikler

  • metrics.impressions
  • metrics.clicks

Aşağıdaki kısıtlamalar nedeniyle bazı alanlara SELECT maddesinde izin verilmeyebilir:

• Seçilemeyen alanları sorgulama Bu alanların Selectable meta veri özelliği false olarak işaretlenir.
• Yinelenen alanların özelliklerini seçme Bu alanların isRepeated meta veri özelliği true olarak işaretlenir.
• FROM clause içinde, söz konusu kaynak için kullanılamayan alanların seçilmesi. Bazı kaynakların özellikleri birlikte seçilemez. Ayrıca, FROM ifadesinde kaynak için yalnızca tüm metriklerin ve segmentlerin bir alt kümesi kullanılabilir.
• Birbiriyle uyumlu olmayan segmentler veya metrikler seçme Bu konu hakkında daha fazla bilgi için segmentasyon bölümüne bakın.

Yukarıdaki koşullarla ilgili bilgileri referans dokümanlarımızda veya GoogleAdsFieldService bulabilirsiniz.

FROM

FROM ifadesi, döndürülecek ana kaynağı belirtir. FROM ifadesindeki kaynak, belirli bir sorgu için diğer tüm ifadelerde hangi alanların kullanılabileceğini tanımlar. FROM ifadesinde yalnızca tek bir kaynak belirtilebilir. GoogleAdsService Search veya SearchStream yöntemlerine yönelik bir sorguda FROM ifadesi zorunludur. Ancak GoogleAdsFieldService kullanılırken FROM ifadesi belirtilmemelidir.

Belirli bir sorgu için FROM ifadesinde yalnızca bir kaynak bulunabilir ancak Atfedilen Kaynaklar'daki alanlar da kullanılabilir. Bu kaynaklar, FROM ifadesindeki kaynakla örtülü olarak birleştirilir. Bu nedenle, değerlerini döndürmek için yalnızca özelliklerini SELECT ifadesine eklemeniz gerekir. Tüm kaynaklarda Atfedilen Kaynaklar özelliği bulunmaz. Aşağıdaki örnekte, reklam gruplarından hem reklam grubu kimliğini hem de kampanya kimliğini isteyebilirsiniz:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Ana kaynağın resource_name alanı her zaman döndürülür. Aşağıdaki örnekte, sorguda açıkça seçilmemiş olmasına rağmen ad_group.resource_name yanıta dahil edilecek:

SELECT ad_group.id
FROM ad_group

En az bir alan seçildiğinde diğer kaynaklar için de aynı durum geçerlidir. Örneğin: campaign.resource_name, aşağıdaki sorgunun yanıtına dahil edilir:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

WHERE ifadesi, istek için veriler filtrelenirken uygulanacak koşulları belirtir. WHERE ifadesi kullanılırken bir veya daha fazla koşul belirtilebilir. Koşulları ayırmak için AND kullanılır. Her koşul, field_name Operator value kalıbına uygun olmalıdır. WHERE ifadesi sorguda isteğe bağlıdır.

Aşağıda, belirli bir dönemdeki metrikleri döndürmek için WHERE kullanımına dair bir örnek verilmiştir:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Verileri filtrelemek için birden fazla koşulu birleştirebilirsiniz. Bu örnek, son 30 gün içinde mobil cihazlarda gösterim alan tüm kampanyaların tıklama sayısını isteyecektir.

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

WHERE ifadesindeki segmentler, SELECT ifadesinde olmalıdır. Temel tarih segmentleri olarak adlandırılan aşağıdaki tarih segmentleri bu kuralın istisnasıdır:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Aşağıdaki sorguda segments.date seçili olduğuna dikkat edin. Bu segment temel bir tarih segmenti olduğundan, WHERE ifadesinde temel tarih segmentlerinden oluşan sınırlı bir tarih aralığı sağlanması gerekir.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Yukarıdaki koşulu karşılayan tüm segmentler şunlardır: segments.date, segments.week, segments.month, segments.quarter ve segments.year. Bu segmentlerden herhangi biri seçilirse WHERE ifadesinde en az birinin kullanılması gerekir.

Filtreleme yaparken operatörünüzün büyük/küçük harfe duyarlılığını göz önünde bulundurmanız önemlidir. Daha fazla bilgi için Büyük/küçük harf duyarlılığı bölümüne bakın.

Operatörlerin tam listesi için dilbilgisi bölümüne bakın.

ORDER BY

ORDER BY ifadesi, sonuçların döndürüleceği sırayı belirtir. Bu sayede, verileri bir alan adına göre artan veya azalan düzende sıralayabilirsiniz. Her sıralama, field_name olarak belirtilir ve ardından ASC veya DESC gelir. ASC veya DESC belirtilmezse varsayılan olarak ASC sırası kullanılır. ORDER BY ifadesi sorguda isteğe bağlıdır.

Aşağıdaki sorgu, döndürülen kampanyaları en yüksekten en düşüğe doğru tıklama sayısına göre sıralar:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Virgülle ayrılmış bir liste kullanarak ORDER BY ifadesinde birden fazla alan belirtebilirsiniz. Sıralama, sorguda belirtilen sırayla yapılır. Örneğin, bu sorguda reklam grubu verileri seçilirken sonuçlar önce kampanya adına göre artan düzende, ardından gösterim sayısına göre azalan düzende, son olarak da tıklama sayısına göre azalan düzende sıralanır:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

SINIRLAMA

LIMIT ifadesi, döndürülecek sonuç sayısını belirtmenize olanak tanır. Bu özellik, yalnızca özetle ilgileniyorsanız yararlıdır.

Örneğin, LIMIT, aşağıdaki sorgunun toplam sonuç sayısını sınırlamak için kullanılabilir:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETRELER

PARAMETERS ifadesi, istek için meta parametreler belirtmenize olanak tanır. Bu parametreler, hangi tür satırların döndürüleceğini etkileyebilir.

Aşağıdaki meta parametreler desteklenir:

include_drafts

Taslak öğelerin döndürülmesine izin vermek için include_drafts değerini true olarak ayarlayın. Varsayılan olarak false değerine ayarlanır.

Örneğin, aşağıdaki sorgu normal kampanyalarla birlikte taslak kampanyaları getirir:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Yanıtın omit_unselected_resource_names bölümündeki her kaynak türünün kaynak adının, SELECT ifadesinde açıkça istenmediği sürece döndürülmesini önlemek için omit_unselected_resource_names değerini true olarak ayarlayın. Varsayılan olarak false değerine ayarlanır.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Ek dil kuralları

Google Ads Sorgu Dili, her bir maddeyle ilgili örneklere ek olarak aşağıdaki davranışları da kullanabilir:

• Sorgu için ana kaynak alanının SELECT ifadesinde olması gerekmez. Örneğin, verileri filtrelemek için yalnızca bir veya daha fazla ana kaynak alanı kullanmak isteyebilirsiniz:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• Metrikler belirli bir kaynak için özel olarak seçilebilir. Sorguda kaynaktan başka alan gerekmez:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• Segmentasyon alanları, eşlik eden kaynak alanları veya metrikler olmadan seçilebilir:

  SELECT segments.device FROM campaign
  

• resource_name alanı (örneğin, campaign.resource_name) verileri filtrelemek veya sıralamak için kullanılabilir:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'