查詢結構

資源、區隔和指標欄位的查詢可傳送至 GoogleAdsService Search 或 SearchStream 方法。如要以 Google Ads 查詢語言建立查詢，您必須採用語言文法建立查詢。查詢由多個子句組成：

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

子句使用「欄位名稱」、「資源名稱」、「運算子」、「條件」和「順序」協助您選取正確的資料。合併為單一查詢後，就能使用 Google Ads API 提出要求。

子句

影片：GAQL 欄位相容性

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
customer.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.costMicros
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'
上一頁
查詢文法
下一頁
日期範圍