Sorgu yapısı

Kaynak, segment ve metrik alanları için sorgular GoogleAdsService Search veya SearchStream yöntemine gönderilebilir. Google Ads sorgu dilinde bir sorgu oluşturmak için dil bilgisi kurallarını kullanın. Google Ads sorgu diline genel bir bakış için Google Ads sorgu diline genel bakış başlıklı makaleyi inceleyin. Sorgular birkaç yan tümceden oluşur:

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

Doğru verileri seçmenize yardımcı olmak için yan tümcelerde alan adları, kaynak adları, operatörler, koşullar ve sıralamalar kullanılı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 yan tümcesinin amacı ve söz dizimi açıklanmaktadır.

SEÇ

SELECT ifadesi, istekte getirilecek bir alan grubunu belirtir. SELECT, virgülle ayrılmış bir kaynak alanları, segment alanları ve metrikler listesi 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 özelliklerin nasıl seçileceğ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
  • 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, belirtilen kaynak için kullanılamayan alanları seçme. Bazı kaynakların özellikleri birlikte seçilemez ve FROM yan tümcesindeki kaynak için tüm metrik ve segmentlerin yalnızca bir alt kümesi kullanılabilir.
  • Birbiriyle uyumlu olmayan segmentler veya metrikler 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 yan tümcesindeki kaynak, belirli bir 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. 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 kaynakların ilişkilendirilmiş kaynağı 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çilmemesine rağmen ad_group.resource_name yanıta dahil edilmiştir:

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 yan tümcesini kullanırken AND ile ayrılmış bir veya daha fazla koşul belirtin. Koşullar genellikle field_name Operator value kalıbını izler (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 örnek, son 30 gün içinde mobil cihazlarda gösterim alan tüm kampanyaların tıklama sayısını ister:

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 yan tümcesindeki segmentler, temel tarih segmentleri olarak adlandırılan aşağıdaki tarih segmentleri hariç olmak üzere SELECT yan tümcesinde de bulunmalıdır:

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

Aşağıdaki sorguda segments.date seçilir. Bu segment temel tarih segmenti olduğundan WHERE ifadesinde temel tarih segmentlerinden oluşan 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 şunlardır: segments.date, segments.week, segments.month, segments.quarter ve segments.year. 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 bilgisi bölümüne 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 ve ardından ASC veya DESC olarak belirtilir. 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 yan tümcesinde birden fazla alan belirtebilirsiniz. Sıralama, sorguda belirtilen sırayla gerçekleşir. Örneğin, reklam grubu verilerini seçen bu sorguda sonuçlar önce kampanya adına göre artan düzende, ardından gösterim sayısına göre azalan düzende ve son olarak 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 sorgu için toplam sonuç sayısını kısıtlayabilir:

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, döndürülen satır türlerini 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 belirtildi ve campaign.resource_name ile customer.resource_name, SELECT yan tümcesinin bir parçası değil.

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

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

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:

  • Sorgu için SELECT yan tümcesinde ana kaynak alanı 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ı