資源、區隔和指標欄位的查詢可傳送至 GoogleAdsService
Search 或 SearchStream 方法。如要以 Google Ads 查詢語言建立查詢,您必須採用語言文法建立查詢。查詢由多個子句組成:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
子句使用「欄位名稱」、「資源名稱」、「運算子」、「條件」和「順序」協助您選取正確的資料。合併為單一查詢後,就能使用 Google Ads API 提出要求。
子句
SELECT
SELECT
子句會指定要在要求中擷取的一組欄位。SELECT
會以半形逗號分隔列出的資源欄位、區隔欄位和指標,並在回應中傳回值。查詢中「必須」使用 SELECT
子句。
以下查詢範例說明如何為指定資源選取屬性:
SELECT
campaign.id,
campaign.name
FROM campaign
您可以在單一要求中要求不同的欄位類型,例如:
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
資源欄位
campaign.id
campaign.name
資源欄位
bidding_strategy.id
bidding_strategy.name
區隔欄位
segments.device
segments.date
指標
metrics.impressions
metrics.clicks
SELECT
子句中可能不允許某些欄位,原因是下列限制:
- 查詢無法選取的欄位。這些欄位的
Selectable
中繼資料屬性會標示為false
。 - 選取重複欄位的屬性。這些欄位的
isRepeated
中繼資料屬性會標示為true
。 - 在
FROM
子句中選取特定資源無法使用的欄位。無法同時選取某些資源的屬性,也只有FROM
子句中的資源可以使用所有指標和區隔的子集。 - 選取彼此不相容的區隔或指標。詳情請參閱區隔一節。
如需上述條件的相關資訊,請參閱我們的參考文件或 GoogleAdsFieldService
。
FROM
FROM
子句會指定要傳回的主要資源。FROM
子句中的資源會定義哪些欄位可用於特定查詢的所有其他子句。您只能在 FROM
子句中指定單一資源。對於 GoogleAdsService
Search 或 SearchStream 方法的查詢中「必填」,此為 FROM
子句,但使用 GoogleAdsFieldService
時「不得」指定子句。
雖然每項查詢的 FROM
子句中只能有 1 項資源,但您也可以取得「Attributed Resources」中的欄位。這些資源會與 FROM
子句中的資源間接彙整,因此您只需將資源屬性加入 SELECT
子句即可傳回值。並非所有資源都有歸因資源。在下方範例中,您可以向廣告群組要求廣告群組 ID 和廣告活動 ID:
SELECT
campaign.id,
ad_group.id
FROM ad_group
系統一律會傳回主要資源的 resource_name
欄位。在以下範例中,儘管查詢中未明確選取,但回應中仍會包含 ad_group.resource_name
:
SELECT ad_group.id
FROM ad_group
其他資源也是同樣的情況,您至少選取一個欄位。例如,campaign.resource_name
會加入下列查詢的回應中:
SELECT
campaign.id,
ad_group.id
FROM ad_group
WHERE
WHERE
子句會指定要在篩選要求資料時套用的條件。使用 WHERE
子句時,可以使用 AND
指定一或多個條件來分隔。每個條件都應採用 field_name Operator value
模式。查詢中的 WHERE
子句是「選用」。
以下範例說明如何使用 WHERE
傳回指定時間範圍的指標:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
您可以結合多個條件來篩選資料。本範例會要求過去 30 天內所有在行動裝置上獲得曝光的廣告活動所獲得的點擊次數。
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
子句中的區隔必須位於 SELECT
子句中,並包含下列日期區段 (稱為「核心日期區隔」),則為例外情況:
segments.date
segments.week
segments.month
segments.quarter
segments.year
請注意,在下列查詢中,已選取 segments.date
。由於這個區隔是核心日期區隔,因此必須提供由 WHERE
子句中核心日期區隔組成的有限日期範圍。
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
符合上述條件的所有區隔為:segment.date、segment.week、segments.month、segment.quarter 和 segment.year。如果選取任一區隔,則 WHERE
子句中必須至少使用其中一個區隔。
篩選時,請務必留意運算子的區分大小寫。詳情請參閱「區分大小寫」。
如需運算子的完整清單,請參閱語言 grammar。
ORDER BY
ORDER BY
子句會指定結果的傳回順序。這可讓您根據欄位名稱,以遞增或遞減順序排列資料。每個順序皆指定為 field_name
,後面接著 ASC
或 DESC
。如未指定 ASC
和 DESC
,順序會預設為 ASC
。查詢中的 ORDER BY
子句是「選用」。
下列查詢會按點擊次數由高至低排序傳回的廣告活動:
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
您可以使用以半形逗號分隔的清單,在 ORDER BY
子句中指定多個欄位。該順序會與查詢中指定的順序相同。
舉例來說,在選取廣告群組資料時,系統會先根據廣告活動名稱遞增排序,再按照曝光次數遞減排序,然後依照點擊次數遞減排序:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
LIMIT
LIMIT
子句可讓您指定要傳回的結果數量。如果您只想查看摘要,這個方法就十分實用。
例如,LIMIT
可用來限制以下查詢的結果總數:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
參數
PARAMETERS
子句可讓您指定要求的中繼資料參數。這些參數可能會影響傳回的資料列類型。
目前支援下列中繼參數:
include_drafts
將 include_drafts
設為 true
,即可允許傳回草稿實體。預設值為 false
。
舉例來說,下列查詢會連同一般廣告活動一併擷取廣告活動草稿:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
omit_unselected_resource_names
將 omit_unselected_resource_names
設為 true
可避免傳回回應中每個資源類型的資源名稱,除非在 SELECT
子句中明確要求。預設為 false
。
allow_unselected_resource_names 範例 | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.resource_name
omit_unselected_resource_names 預設為 false ,因此系統會傳回所有 resource_name 欄位。 |
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: 無。 omit_unselected_resource_names 指定為 true ,
campaign.resource_name ,customer.resource_name 並非 SELECT 子句的一部分。
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource:campaign.resource_name
omit_unselected_resource_names 指定為 true ,campaign.resource_name 要求是 SELECT 子句的一部分。 |
其他語言規則
除了每個子句的範例之外,Google Ads 查詢語言還有下列可用行為:
查詢時,主要資源欄位「不需要」加入
SELECT
子句。舉例來說,您可能只想使用一或多個主要資源欄位來篩選資料:SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
只能為特定資源選取指標;查詢時不需要提供資源中的其他欄位:
SELECT metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign
您可以選取區隔欄位,而不一併選取任何相關的資源欄位或指標:
SELECT segments.device FROM campaign
resource_name
欄位 (例如campaign.resource_name
) 可用來篩選或排序資料:SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'