查詢結構

資源、區隔和指標欄位的查詢可以傳送至 GoogleAdsService 「Search」或 「SearchStream」方法。如要使用 Google Ads 查詢語言建構查詢，必須使用語言文法。如需 Google Ads 查詢語言的一般總覽，請參閱 Google Ads 查詢語言總覽。查詢由多個子句組成：

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

子句會使用欄位名稱、資源名稱、運算子、條件和排序，協助您選取正確的資料。合併為單一查詢後，即可使用 Google Ads API 發出要求。

子句

以下各節說明每個 Google Ads 查詢語言子句的用途和語法。

選取

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
  • 查詢無法選取的欄位。這些欄位的 selectable 中繼資料屬性會標示為 false。
  • 選取重複欄位的屬性。這些欄位的 is_repeated 中繼資料屬性會標示為 true。
  • 在 FROM子句中選取指定資源沒有的欄位。部分資源的屬性無法同時選取，且只有所有指標和區隔的子集可用於 FROM 子句中的資源。
  • 選取的區隔或指標彼此不相容。詳情請參閱區隔章節。

如要瞭解上述條件的相關資訊，請參閱參考文件或 GoogleAdsFieldService。

FROM

FROM 子句會指定要傳回的主要資源。FROM 子句中的資源會定義特定查詢的所有其他子句中可使用的欄位。FROM 子句中只能指定單一資源。在查詢中，FROM 子句是必要項目，用於 GoogleAdsService Search 或 SearchStream 方法。不過，使用 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 模式 (或使用 BETWEEN value AND value、IS NULL 或 IS NOT NULL)。查詢中的 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 子句可讓您指定要求的 meta 參數。這些參數可能會影響傳回的資料列類型。

系統支援下列中繼參數：

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