查詢結構

資源、區隔和指標欄位的查詢可以傳送至 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 子句。

雖然在特定查詢的 FROM 子句中只能存在一個資源，但也可能會提供來自已指派資源的欄位。這些資源會隱含地與 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

符合上述條件的所有區隔：segments.date、segments.week、segments.month、segments.quarter 和 segments.year。如果選取任何這些區段，則必須在 WHERE 子句中使用其中至少一個區段。

篩選時，請務必留意運算子的大小寫敏感度。詳情請參閱「大小寫敏感性」。

如需完整的運算子清單，請參閱語言文法。

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。

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