Sorgu yapısı

Kaynak, segment ve metrik alanları için sorgular GoogleAdsService Search veya SearchStream yöntemine gönderilebilir. Google Ads Sorgu Dili'nde sorgu oluşturmak için dil bilgisi kurallarını kullanın. Google Ads Sorgu Dili'ne genel bir bakış için Google Ads Sorgu Dili'ne genel bakış başlıklı makaleyi inceleyin. Sorgular birkaç yan tümceden 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. Tek bir sorguda birleştirildikten sonra isteği Google Ads API'ye gönderebilirsiniz.

Maddeler

Aşağıdaki bölümlerde her bir Google Ads sorgu dili ifadesinin amacı ve söz dizimi açıklanmaktadır.

SEÇ

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

Aşağıdaki örnek sorguda, belirli bir kaynak için özelliklerin seçilmesiyle ilgili bir örnek 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
  • Ana kaynak alanları
    • campaign.id
    • campaign.name
  • İlişkilendirilmiş kaynak alanları
    • bidding_strategy.id
    • bidding_strategy.name
  • Segment alanları
    • segments.device
    • segments.date
  • Metrikler
    • metrics.impressions
    • metrics.clicks
  • Seçilemeyen alanları sorgulama. Bu alanların selectable meta veri özelliği false olarak işaretlenmiştir.
  • Yinelenen alanların özelliklerini seçme Bu alanların is_repeated meta veri özelliği true olarak işaretlenmiştir.
  • FROM Yan tümcesinde, söz konusu kaynak için kullanılamayan alanların seçilmesi. Bazı kaynakların özellikleri birlikte seçilemez ve FROM yan tümcesindeki kaynak için tüm metriklerin ve segmentlerin yalnızca bir alt kümesi kullanılabilir.
  • Birbiriyle uyumlu olmayan segmentleri veya metrikleri seçme Daha fazla bilgi için Segmentasyon başlıklı makaleyi inceleyin.

Yukarıdaki koşullarla ilgili bilgileri referans belgelerimizde veya GoogleAdsFieldService adresinde 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 yan tümcesinde yalnızca tek bir kaynak belirtilebilir. GoogleAdsService Search veya SearchStream yöntemine yönelik bir sorguda FROM ifadesi zorunludur. Ancak GoogleAdsFieldService kullanılırken FROM ifadesi belirtilmemelidir.

Belirli bir sorgu için FROM yan tümcesinde yalnızca bir kaynak bulunabilir ancak ilişkilendirilen kaynaklardaki alanlar da kullanılabilir. Bu kaynaklar, FROM yan tümcesindeki kaynakla dolaylı olarak birleştirilir. Bu nedenle, değerlerini döndürmek için özelliklerini SELECT yan tümcesine eklemeniz yeterlidir. Tüm kaynaklarda ilişkilendirilmiş 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, sorguda açıkça seçilmemiş olmasına rağmen ad_group.resource_name yanıta dahil ediliyor:

SELECT ad_group.id
FROM ad_group

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

WHERE ifadesi, istek için veriler filtrelenirken uygulanacak koşulları belirtir. WHERE ifadesini kullanırken AND ile ayrılmış bir veya daha fazla koşul belirtin. Koşullar genellikle field_name Operator value kalıbını kullanır (veya BETWEEN value AND value, IS NULL ya da IS NOT NULL kullanır). WHERE ifadesi sorguda isteğe bağlıdır.

Aşağıdaki örnekte, belirli bir dönemdeki metrikleri döndürmek için WHERE kullanılmaktadır:

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 alan tüm kampanyaların tıklama sayısı istenmektedir:

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, temel tarih segmentleri olarak adlandırılan aşağıdaki tarih segmentleri hariç SELECT ifadesinde de yer almalıdır:

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

Aşağıdaki sorguda segments.date seçilmiştir. Bu segment temel tarih segmenti olduğundan temel tarih segmentlerinden oluşan WHERE ifadesinde sınırlı bir tarih aralığı belirtmeniz 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 segments.date, segments.week, segments.month, segments.quarter ve segments.year'dir. Bu segmentlerden herhangi biri seçilirse en az biri WHERE yan tümcesinde kullanılmalıdır.

Tarih filtreleme hakkında daha fazla bilgi için Tarih aralıkları başlıklı makaleyi inceleyin.

Filtreleme yaparken operatörünüzün büyük/küçük harfe duyarlılığını göz önünde bulundurun. 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 dil gramerine bakın.

ORDER BY

ORDER BY ifadesi, sonuçların döndürüleceği sırayı belirtir. Bu işlem, verileri bir alan adına göre artan veya azalan düzende düzenlemenize olanak tanır. Her sıralama, field_name ile belirtilir ve ardından ASC veya DESC gelir. ASC veya DESC belirtilmezse sıralama varsayılan olarak ASC olur. Sorguda ORDER BY ifadesi 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ış liste kullanarak ORDER BY ifadesinde birden fazla alan belirtebilirsiniz. Sıralama, sorguda belirtilen sırayla gerçekleşir. Örneğin, bu sorguda reklam grubu verileri seçildiğinde 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, sonuçların yalnızca bir alt kümesine ihtiyacınız varsa kullanışlıdır.

Örneğin, LIMIT aşağıdaki sorgunun toplam sonuç sayısını sınırlayabilir:

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ürde satırların döndürüleceğini etkileyebilir.

Aşağıdaki meta parametreler desteklenir:

include_drafts

Taslak öğeleri döndürmek için include_drafts değerini true olarak ayarlayın. Varsayılan değer false'dir.

Örneğin, aşağıdaki sorgu normal kampanyalarla birlikte taslak kampanyaları da 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ı atlamak için omit_unselected_resource_names değerini true olarak ayarlayın. Varsayılan değer false'dir.

Sorgu İade edilen kaynaklar 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • 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

Yok

omit_unselected_resource_names, true olarak belirtilir ve campaign.resource_name ile customer.resource_name, SELECT ifadesinin bir parçası değildir.

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

omit_unselected_resource_names, true olarak belirtilmişse ve campaign.resource_name, SELECT ifadesinin bir parçası olarak isteniyorsa.

Ek dil kuralları

Google Ads Sorgu Dili, her bir yan tümce için verilen örneklere ek olarak aşağıdaki davranışları da destekler:

  • Ana kaynak alanı, bir sorgu için SELECT ifadesinde gerekli değildir. Örneğin, verileri seçmeden filtrelemek için bir veya daha fazla ana kaynak alanı kullanabilirsiniz:

    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 herhangi bir kaynak alanı veya metrik olmadan seçilebilir:

    SELECT segments.device FROM campaign

  • resource_name alanı (ör. 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ı