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

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

查詢結構和子句

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

子句使用欄位名稱、資源名稱、運算子、條件、和 orderings 搭配使用，以合併到單一查詢要求。

簡單來說，如何建構查詢：

指定要從中擷取資料的資源。
新增欄位和指標，定義要傳回的資料。
新增區隔，將結果分組。
新增歸因資源以間接彙整相關資源資料。
您可以篩選、排序並限制結果範圍。

`SELECT` 子句

SELECT 子句：

是查詢中的 required 子句。
指定要求中要擷取的一組欄位。
這會採用以半形逗號分隔的資源欄位、自訂欄、自訂清單 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 自訂變數

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

在本例中，查詢包含 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.resource_name 會包含在因為已選取 campaign.id：

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'

多個條件

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

這個查詢範例要求所有廣告活動的clicks指標數量和impressions指標。

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 子句中使用核心日期區隔來指定日期或時間。

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

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 子句中指定多個欄位，並以半形逗號分隔請參考閱讀清單，進一步瞭解如何選擇 Kubeflow Pipelines SDK 或 TFX結果會依照您在。

此查詢範例會選取廣告群組資料，並按遞增順序排序結果依廣告活動名稱排序，然後是按曝光次數遞減排序，以及然後再按點擊次數遞減排序：

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 參數可讓您排除擁有資源中未明確要求的所有資源的 resource_name 欄位 SELECT 子句。預設為 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 格式的貨幣代碼。例如：美元、歐元。

這個範例查詢會傳回 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"

瞭解詳情

查詢文法