Sorgu Yapısı

Kaynak, segment ve metrik alanları için sorgular GoogleAdsService Search veya SearchStream yöntemlerine gönderilebilir. Google Ads Sorgu Dili ile sorgu oluşturmak için bu sorguyu dil dilbilgisi ile oluşturmanız gerekir. Sorgu, bir dizi maddeden oluşur:

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

Maddeler, 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. Birleştirildikten sonra, Google Ads API kullanılarak bir istek gönderilebilir.

Maddeler

Video: GAQL Alan Uyumluluğu

SELECT

SELECT ifadesi, istekte getirilecek bir grup alanı belirtir. SELECT; kaynak alanlarının, segment alanlarının ve metriklerin virgülle ayrılmış bir listesini alarak yanıttaki değerleri döndürür. SELECT deyimi bir sorguda zorunludur.

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

SELECT
  campaign.id,
  campaign.name
FROM campaign

Tek bir istekte farklı alan türlerini 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 SELECT yan tümcesinde bazı alanlara izin verilmeyebilir:

  • Seçilemeyen alanları sorguluyor. Bu alanların Selectable meta veri özelliği false olarak işaretlenir.
  • Tekrarlanan alanların özelliklerini seçme. Bu alanların isRepeated meta veri özelliği true olarak işaretlenir.
  • FROM yan tümcesinde belirtilen kaynak için kullanılamayan alanları seçme. Bazı kaynakların özellikleri birlikte seçilemez. Ayrıca, FROM ifadesinde kaynak için tüm metriklerin ve segmentlerin yalnızca bir alt kümesi kullanılabilir.
  • Birbiriyle uyumlu olmayan segmentleri veya metrikleri seçmek. Bu konu hakkında daha fazla bilgi için segmentasyon bölümüne bakın.

Yukarıdaki koşullarla ilgili bilgileri referans belgelerimizde veya GoogleAdsFieldService adresinde bulabilirsiniz.

FROM

FROM deyimi, döndürülecek ana kaynağı belirtir. FROM yan tümcesindeki kaynak, belirtilen sorgu için diğer tüm yan tümcelerde hangi alanların kullanılabileceğini tanımlar. FROM yan tümcesinde yalnızca tek bir kaynak belirtilebilir. FROM ifadesi, GoogleAdsService Search veya SearchStream yöntemleri için yapılan bir sorguda zorunludur ancak GoogleAdsFieldService kullanılırken belirtilmemesi gerekir.

Belirli bir sorgunun FROM yan tümcesinde yalnızca 1 kaynak bulunabilir. Bununla birlikte, İlişkilendirilmiş Kaynaklar'daki alanlar da kullanılabilir. Bu kaynaklar FROM yan tümcesindeki kaynakla dolaylı olarak birleştirilir. Bu nedenle, değerlerini döndürmek için yalnızca özelliklerini SELECT ifadesine eklemeniz gerekir. Tüm kaynaklarda İlişkilendirilen Kaynaklar yoktur. 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 ad_group.resource_name, sorguda açıkça seçilmemesine rağmen yanıta dahil edilecektir:

SELECT ad_group.id
FROM ad_group

Aynı durum, en az bir alan seçildiğinde diğer kaynaklar için de 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 verileri filtrelerken uygulanacak koşulları belirtir. WHERE ifadesi kullanıldığında, bunları ayırmak için AND kullanılarak bir veya daha fazla koşul belirtilebilir. Her koşul field_name Operator value kalıbına uymalıdır. WHERE deyimi sorguda isteğe bağlıdır.

Aşağıda, belirli bir dönemdeki metrikleri döndürmek için WHERE özelliğinin kullanımına 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 örnekte, son 30 gün içinde mobil cihazlarda gösterim almış tüm kampanyalar için tıklama sayısı istenecek.

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 yantümcesindeki segmentler, temel tarih segmentleri olarak adlandırılan aşağıdaki tarih segmentleriyle SELECT ifadesinde olmalıdır. İstisnalar şunlardır:

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

Aşağıdaki sorguda segments.date değerinin seçildiğini unutmayın. Bu segment temel bir tarih segmenti olduğundan, WHERE ifadesindeki temel tarih segmentlerinden oluşan sınırlı bir tarih aralığının 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 biri kullanılmalıdır.

Filtreleme sırasında operatörünüzün büyük/küçük harfe duyarlılığını göz önünde bulundurmanız gerekir. Daha ayrıntılı bilgi için Büyük/küçük harfe duyarlılık bölümüne bakın.

Operatörlerin tam listesi için dil dil bilgisine bakın.

ORDER BY

ORDER BY yantümcesi, sonuçların hangi sırayla döndürüleceğini belirtir. Bu, verileri alan adına göre artan veya azalan sırada düzenlemenize olanak tanır. Her bir sıralama, bir field_name ve ardından ASC veya DESC ile belirtilir. ASC veya DESC belirtilmezse sıra varsayılan olarak ASC olur. ORDER BY deyimi sorguda isteğe bağlıdır.

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

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

Virgülle ayrılmış bir liste kullanarak ORDER BY yan tümcesinde birden fazla alan belirtebilirsiniz. Sıralama, sorguda belirtilen sırayla gerçekleşir. Örneğin, reklam grubu verilerinin seçildiği bu sorguda sonuçlar, kampanya adına göre artan düzende, ardından gösterim sayısına göre azalan düzende, sonra 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

SINIR

LIMIT ifadesi, döndürülecek sonuç sayısını belirtmenizi sağlar. Bu, yalnızca bir özetle ilgileniyorsanız yararlı olur.

Örneğin, aşağıdaki sorgu için toplam sonuç sayısını kısıtlamak amacıyla LIMIT 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 parametreleri belirtmenizi sağlar. Bu parametreler, ne tür satırların döndürüleceğini etkileyebilir.

Şu anda, aşağıdaki meta parametreler desteklenmektedir:

include_drafts

Taslak varlıkların 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 taslak kampanyaları normal kampanyalarla birlikte getirir:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

SELECT yan tümcesinde açıkça istenmediği sürece yanıttaki her kaynak türünün kaynak adının 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.

omit_unselected_resource_names örnekleri
SELECT
  campaign.name,
  customer.id
FROM campaign
Returned resources:
campaign.resource_name
customer.resource_name
omit_unselected_resource_names varsayılan olarak false değerine ayarlanır, bu nedenle tüm resource_name alanları döndürülür. 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Returned resources:
Yok.
omit_unselected_resource_names, true olarak belirtilir ve campaign.resource_name ve customer.resource_name SELECT koşulunun bir parçası değildir. 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Returned resource:
campaign.resource_name
omit_unselected_resource_names, true olarak belirtildi ve campaign.resource_name, SELECT yan tümcesinin bir parçası olarak istendi.

Ek dil kuralları

Her bir madde için verilen örneklere ek olarak, Google Ads Sorgu Dili'nde aşağıdaki davranışlar da kullanılabilir:

  • Ana kaynak alanının bir sorgunun SELECT yan tümcesinde yer alması için zorunlu değildir. Ö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 herhangi bir alan gerekmez:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.costMicros
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'
Önceki
Sorgu dil bilgisi
Sonraki
Tarih aralıkları