新版 Search Ads 360 Reporting API 現已開放使用。歡迎加入 searchads-api-announcements Google 群組，即時掌握即將發布的強化項目和版本資訊。

本頁面由 Cloud Translation API 翻譯而成。

查詢結構和子句

查詢由多個子句組成：SELECT、FROM、WHERE、ORDER BY、LIMIT 和 PARAMETERS。

子句會使用合併成單一查詢要求的欄位名稱、資源名稱、運算子、條件和排序。

簡單來說，建立查詢時，您需要：

指定要擷取資料的資源。
新增欄位和指標，定義要傳回的資料。
新增區隔來將結果分組。
新增歸因資源以間接彙整相關資源資料。
篩選、排序及限制結果數量。

`SELECT` 子句

SELECT 子句：

是查詢中必填的子句。
指定要求中要擷取的一組欄位。
接收以逗號分隔的資源欄位、自訂欄、自訂 Floodlight 變數、區隔欄位和指標清單，並在回應中傳回這些值。

以下查詢範例說明如何選取 campaign 資源的屬性：

SELECT
  campaign.id,
  campaign.name
FROM campaign

多個欄位類型

您可以在同一個要求中要求不同的欄位類型。

下方查詢範例顯示了含有下列組合的單一查詢：

資源欄位：campaign.id、campaign.name、bidding_strategy.id 和 bidding_strategy.name。
區隔欄位：segments.device 和 segments.date。
指標欄位：metrics.impressions 和 metrics.clicks。

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

請參閱「區隔」一文，進一步瞭解如何區隔搜尋報表。

主要資源欄位

通常，您會在 SELECT 子句中加入主要資源欄位，但這不是必要條件 (不強制規定)。

這個範例查詢會使用主要資源欄位 (ad_group.status) 篩選結果。

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

Floodlight 自訂變數

您可以使用 ID 在 SELECT 子句中加入 Floodlight 自訂變數。

在這個範例中，查詢包含廣告活動資源 ID 為 123454321 的自訂變數。

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

自訂欄

您可以使用 ID 在 SELECT 子句中加入自訂欄。

在本例中，查詢包含廣告活動資源的 ID 12345678 自訂欄。

SELECT
  custom_columns.id[12345678]
FROM campaign

請參閱如何取得自訂欄 ID。

指標欄位

您可以選取特定資源的指標欄位，而不需要在 SELECT 子句中加入該資源的任何其他欄位。

此查詢範例會為 campaign 資源選取 impressions 和 clicks 指標。

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

如要瞭解可在查詢中使用的指標欄位清單，請參閱 metrics。

區隔欄位

您可以選取區隔欄位，不必在 SELECT 子句中指定隨附的資源欄位或指標。

這個範例查詢會按裝置劃分結果。

SELECT segments.device
FROM campaign

如要查看可在查詢中使用的區隔欄位清單，請參閱 segments。

禁止欄位

您無法在 SELECT 子句中使用下列欄位：

無法選取的欄位，也就是含有 Selectable 中繼資料屬性標示為 false 的欄位。
重複欄位，也就是 Repeated 中繼資料屬性標示為 true 的欄位。
在 FROM 子句中，不適用於指定資源的欄位。部分資源的屬性無法同時選取。部分資源只會提供所有指標和區隔的一小部分。
不相容的區隔或指標。詳情請參閱「區隔」。

如要進一步瞭解如何查看每項資源的這項資訊，請參閱參考文件。

FROM 子句

FROM 子句：

這是必要的 SearchAds360Service 查詢子句 (包括 Search 和 SearchStream 方法)。
對於對 SearchAds360FieldService 的查詢，「請勿」加入此屬性。
指定查詢傳回的主要資源。
只能指定單一資源。
定義可在查詢中所有其他子句中使用的欄位。

已歸因的資源

如果可用的屬性資源，會與您在 FROM 子句中指定的資源隱含地彙整。您只需將這些屬性加入 SELECT 子句，即可傳回這些屬性的值。

這個範例查詢會傳回廣告群組 ID 和廣告活動 ID，因為 campaign 是 ad_group 資源的屬性資源。

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

`resource_name` 欄位

系統一律會傳回 FROM 子句中主要資源的 resource_name 欄位。

在這個範例查詢中，即使在查詢中未明確選取 ad_group.resource_name，也會將其納入回應：

SELECT ad_group.id
FROM ad_group

選取至少一個欄位時，系統會傳回已指派資源的 resource_name 欄位。

在這個範例查詢中，由於選取了 campaign.id，因此 campaign.resource_name 會包含在回應中：

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE 子句

WHERE 子句：

是查詢中的選用子句。
指定依要求篩選及區隔資料的條件。條件遵循以下模式：FIELD_NAME OPERATOR VALUE (以空格分隔)。
可包含多個條件，並以 AND 分隔符分隔。

以下查詢範例說明如何使用 WHERE 子句，傳回特定時間範圍內的 impressions 指標：

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

請參閱「區隔」一文，進一步瞭解如何區隔搜尋報表。

如要進一步瞭解如何在查詢中指定日期範圍，請參閱「日期範圍」。

依「`resource_name`」欄位篩選

您可以使用 resource_name 欄位篩選或排序資料。

以下範例查詢會使用 campaign.resource_name 欄位，依特定廣告活動篩選結果：

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

多個條件

您可以合併多個條件來篩選資料。

此查詢範例針對在過去 30 天內，在行動裝置上使用 impressions 指標的所有廣告活動要求 clicks 指標的數量。

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

如要進一步瞭解如何區隔報表，請參閱「區隔」一文。

區分大小寫

篩選字串值時，每個運算子的預設大小寫敏感度會對正確篩選結果發揮重要作用。

下表列出每個運算子的預設大小寫敏感度。

預設區分大小寫
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

您可以使用 (?i) 修飾符，將 REGEXP_MATCH 和 NOT REGEXP_MATCH 的預設敏感度變更為不區分大小寫，例如：

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

如要查看可用來篩選資料的完整運算子清單，請參閱查詢語法參考資料。

核心日期區隔

以下區隔欄位稱為「核心日期區隔」：segments.date、segments.week、segments.month、segments.quarter 和 segments.year。

您可以在 WHERE 子句中使用核心日期區隔，指定日期或時間範圍。

以下範例查詢會在 WHERE 子句中，為 segments.date 欄位指定 DURING LAST_30_DAYS：

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

如要進一步瞭解如何使用核心日期區隔，請參閱「區隔」>「核心日期區隔」。

禁止篩選

不允許篩選：

來自未選取的區隔欄位，核心日期區隔除外。
在任何訊息類型的欄位中，除了基本類型 (例如 Int64Value、StringValue 等) 以外。
在任何郵件類型的重複欄位屬性上 (原始欄位除外，例如 Int64Value、StringValue 等)。

ORDER BY 子句

ORDER BY 子句：

是查詢中的選用子句。
指定結果的傳回順序。排序模式如下：FIELD_NAME ORDERING_OPTION (以空格分隔)。
允許兩個選項：ASC (遞增) 或 DESC (遞減)。預設為遞增。

此查詢範例會按照點擊次數以遞減順序 (由高到低) 將廣告活動排序：

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

結合排序和限制

您可以使用 ORDER BY 子句搭配 LIMIT 子句，進一步精確指定結果。

以下範例查詢會傳回過去 30 天內曝光次數最高的五個廣告活動：

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

禁止排序

不允許訂購：

根據未選取資源的屬性。
依據未選取的指標。
依據未選取的區隔。
針對這些欄位類型：
- MESSAGE
- 重複欄位
- 重複欄位的屬性。

LIMIT 子句

LIMIT 子句：

是查詢中的選用子句。
可讓您限制查詢傳回的結果數量。

舉例來說，如果您只需要結果樣本或摘要，這個子句就很實用。

這個範例查詢會將結果總數限制在 50 個：

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETERS 子句

PARAMETERS 子句可讓您指定要求的元資料參數。

納入草稿

include_drafts 參數可控制是否要在結果中加入草稿實體。預設為 false。將其設為 true 即可納入草稿實體。

以下範例查詢會傳回草稿廣告活動和一般廣告活動：

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

省略已取消選取的 `resource_name`

omit_unselected_resource_names 參數可讓您排除 SELECT 子句中未明確要求的所有資源的 resource_name 欄位。預設為 false。如果您將這個參數設為 true，建議您在 SELECT 子句中明確要求主要資源的資源名稱，以及任何屬性資源。

這項範例查詢不會傳回 campaign.resource_name 或 customer.resource_name 欄位，因為這些欄位不在 SELECT 子句中：

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

這項範例查詢會傳回 campaign.resource_name 欄位，因為 SELECT 子句中明確要求這個欄位：

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

變更指標使用的貨幣

您可以使用 metrics_currency 參數，在計算 SELECT 子句中納入的指標時指定要使用的幣別。預設會使用帳戶的當地幣別。如果您設定這個參數，就必須使用 ISO 4217 3 個字元的貨幣代碼。例如：美元、歐元。

這個範例查詢會以帳戶的當地幣別傳回 cost_micros 指標。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

這個範例查詢會以智利披索 (CLP) 傳回 cost_micros 指標。

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

瞭解詳情

查詢語法