查詢結構

提示： 使用互動式查詢建立工具建構及驗證 Google Ads 查詢語言查詢。

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

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

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

重點： GoogleAdsFieldService 為 Google Ads 查詢語言用戶端提供目錄，其中包含所有資源欄位、區隔欄位和指標的中繼資料、彼此之間的關係，以及在各子句中的可用性。由於可查詢的資源、欄位、區隔和指標組合會因 API 主要版本而異，因此請在目標 API 版本的端點查詢 GoogleAdsFieldService。詳情請參閱 GoogleAdsField 和「各版本差異」一文。

子句

以下各節將說明每個 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

注意： 由於下列限制，部分欄位無法在 SELECT 子句中選取：

• 查詢無法選取的欄位。這些欄位的 selectable 中繼資料屬性會標示為 false。
• 選取重複欄位的屬性。這些欄位的 is_repeated 中繼資料屬性會標示為 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

重點： 如果 FROM 子句中的資源將其他資源列為 segment，則選取該資源的任何屬性都會做為區隔。

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 子句中使用其中一個區隔。

如要進一步瞭解日期篩選功能，請參閱「日期範圍」。

重點提示： 分隔符 AND 只能用於運算子條件 (WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE') 之間，不能用於單一運算子條件 (WHERE segments.device != 'DESKTOP' AND 'MOBILE') 內。

篩選時，請留意運算子是否區分大小寫。 詳情請參閱「大小寫區分」。

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

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

重點： LIMIT 可讓您截斷結果。如要擷取大型結果集而不截斷，請使用 GoogleAdsService.SearchStream 串流資料列，或使用 GoogleAdsService.Search 分頁。

參數

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。

注意： 如果您打算使用任何傳回的物件進行更新或移除作業，建議將這個選項設為 false，因為沒有資源名稱的資源無法用於變動作業。如果將這個選項設為 true，請務必明確要求主要資源和您使用查詢擷取的任何歸因資源的資源名稱。

查詢	傳回的資源
SELECT campaign.name, customer.id FROM campaign	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	無 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	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'