請參閱下列各節,瞭解如何在 Search Ads 360 Reporting API 中建立搜尋報表。
搜尋服務
Search Ads 360 Reporting API 提供了特殊的服務,可用於搜尋及製作報表。
SearchAds360Service
是統合的物件擷取與報表服務,提供 SearchStream
和 Search
這兩種搜尋方法。系統會使用以 Search Ads 360 查詢語言撰寫的查詢字串傳遞搜尋。您可以將查詢定義為:
- 擷取物件的特定屬性。
- 根據日期範圍擷取物件的成效指標。
- 根據物件屬性將物件排序。
- 使用條件來指定要傳回哪些物件,藉此篩選結果
- 限制傳回的物件數量。
這兩種搜尋方法都會傳回符合查詢的所有資料列。舉例來說,當您擷取 campaign.id
、campaign.name
和 metrics.clicks
時,API 會傳回 SearchAds360Row
,其中包含廣告活動物件的 id
和 name
欄位組合,以及一個 metrics
物件並設定其 clicks
欄位。
搜尋方法
SearchStream
無論報表大小,傳送單一要求並與 Search Ads 360 Reporting API 建立永久連線。
- 系統會立即開始下載資料封包,並在資料緩衝區中快取整個結果。
- 程式碼不必等待整個串流完成,就能開始讀取緩衝的資料。
Search
傳送多個分頁要求來下載整份報表。
SearchStream
通常效能較佳,因為這種做法可以省去要求個別網頁所需的往返網路時間。如果報表列超過 10,000 列,建議您使用 SearchStream
。小型報表 (<10,000 列) 的方法沒有顯著的效能差異。
您使用的方法不會影響 API 配額與限制:無論結果是分頁或串流,單一查詢或報表都計為一次作業。
搜尋查詢範例
此查詢範例會傳回帳戶最近 30 天內的成效資料,並按裝置區隔:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
提出要求
如要發出要求,您必須將 customer_id
和 query
字串傳遞至 SearchAds360Service.SearchStream
或 SearchAds360Service.Search
介面。
這項要求內含向 Search Ads 360 Reporting API 伺服器發出的 HTTP POST
,位於下列其中一個網址:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
以下是 HTTP POST
要求中包含的 searchStream
報表定義完整範例:
POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1 Host: searchads360.googleapis.com User-Agent: curl Content-Type: application/json Accept: application/json Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN] Parameters: { "query" : "SELECT campaign.name, campaign.status, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS" }
處理回應
SearchAds360Service
會傳回 SearchAds360Row
物件的清單。
每個 SearchAds360Row
都代表查詢傳回的物件。每個物件都含有一組屬性,系統會根據查詢的 SELECT
子句中要求的欄位填入這些屬性。系統不會在回應的物件中填入未包含在 SELECT
子句的屬性。
舉例來說,下方的查詢只會將 campaign.id
、campaign.name
和 campaign.status
填入每個 SearchAds360Row
物件。系統會省略 campaign.engine_id
或 campaign.bidding_strategy_type
等其他屬性。
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
參考說明文件
「參考資料」部分包含正確使用每個構件所需的一切資訊。每項資源都有一個頁面,例如 ad_group
和 campaign
。segments
和 metrics
頁面會列出所有可用的區隔和指標欄位。
部分資源、區隔和指標彼此不相容且無法同時使用,而其他資源則完全相容且相輔相成。每個資源頁面都會提供以下資訊 (如有) 和其他資訊:
- 歸因資源
針對部分資源,您可以選擇透過選取資源欄位與
FROM
子句中的資源欄位,以隱含方式彙整相關資源。舉例來說,campaign
資源是ad_group
資源的歸因資源。也就是說,在FROM
子句中使用ad_group
時,您可以在查詢中加入campaign.id
和campaign.bidding_strategy_type
等欄位。「歸因資源」部分會列出可用的歸因資源。並非所有資源都有已歸因的資源。
- 資源欄位欄
「資源欄位」欄會納入資源的所有欄位。每個資源欄位都會連結至欄位的更多詳細資料,包括說明、類別、資料類型、類型網址,以及可篩選、可選取、排序和重複設定。
- 區隔欄
特定資源無法選取部分區隔欄位。
「Segments」(區隔) 資料欄列出
segments
欄位,您可以在相同的SELECT
子句中做為資源欄位使用。每個欄位都會連結至欄位的完整詳細資料,包括說明、類別、資料類型、類型網址,以及可篩選、選取、排序和重複設定。如果您在FROM
子句中使用資源,可以使用「Yes/No」下拉式選單來篩除無法使用的區隔。- 指標欄
使用某項資源時,並非所有指標欄位都可供選取。
「Metrics」欄列出
metrics
欄位,您可以在與資源欄位相同的SELECT
子句中。每個欄位都會連結至欄位的完整詳細資料,包括說明、類別、資料類型、類型網址,以及可篩選、選取、排序和重複設定。如果您在FROM
子句中使用資源,請使用「Yes/No」下拉式選單篩除無法使用的指標。
- 區隔資源
部分資源具有區隔資源欄位,您可以在
FROM
子句中選取所需資源。舉例來說,如果您選取campaign.name
等campaign
資源欄位,則當您在FROM
子句中使用campaign_budget
時,將會自動傳回campaign.resource_name
並進行區隔,因為campaign
是campaign_budget
的區隔資源。「區隔資源」區段會列出可用的區隔資源。並非所有資源都有區隔資源。
- 適用選項
部分
segments
欄位與其他資源、區隔和指標不相容。segments
頁面為每個segments
欄位提供「可選取項目」,其中會列出所有相容資源欄位、metrics
欄位,以及可加入SELECT
子句的其他segments
欄位。
區隔
您可以在查詢的 SELECT
子句中加入 segments.FIELD_NAME
欄位,將搜尋結果區隔開來。
例如,在下方查詢中的 segments.device
會產生報告,針對 FROM
子句中指定的資源,每部裝置的 impressions
各一列。
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
SearchAds360Service.SearchStream
傳回的結果看起來會像這樣:JSON 字串:
{
"results":[
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"10922"
},
"segments":{
"device":"MOBILE"
}
},
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"28297"
},
"segments":{
"device":"DESKTOP"
}
},
...
]
}
如需可用的區隔欄位清單,請參閱 segments
。
多個區隔
您可以在查詢的 SELECT
子句中指定多個區隔。回應中會包含一個 SearchAds360Row
物件,每個 SearchAds360Row
物件會對應至 FROM
子句指定的主要資源執行個體組合,以及每個所選 segment
欄位的 value。
舉例來說,下列查詢會針對 campaign
、segments.ad_network_type
和 segments.date
的每個組合傳回一個資料列。
SELECT
segments.ad_network_type
segments.date
FROM campaign
請注意,結果會由主要資源的每個執行個體隱含區隔,而非個別所選欄位的值。
以下查詢結果會為每個廣告活動產生一列,而不是每個與 campaign.status
欄位不同的值一列。
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
隱性區隔
每份報表一開始都是依 FROM
子句中指定的資源區隔。指標是按照這項資源的 resource_name
欄位區隔而來
這個範例查詢會自動傳回 ad_group.resource_name
,並以隱含方式使用它來區隔 ad_group
層級的指標。
SELECT metrics.impressions
FROM ad_group
傳回的 JSON 字串類似下列內容:
{
"results":[
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/2222222222"
},
"metrics":{
"impressions":"237"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/33333333333"
},
"metrics":{
"impressions":"15"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/44444444444"
},
"metrics":{
"impressions":"0"
}
}
]
}
核心日期區隔
您可以在 WHERE
子句中使用核心日期區隔來指定日期或時間範圍。
下列區隔欄位稱為核心日期區隔:segments.date
、segments.week
、segments.month
、segments.quarter
和 segments.year
。
以下查詢範例會傳回過去 30 天的廣告活動 clicks
指標。
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
核心日期區隔欄位屬於一般規則的「例外」,除非在 SELECT
子句中加入該欄位,否則您不得在 WHERE
子句中使用區隔欄位。詳情請參閱「禁止篩選」一節。
核心日期區隔規則:
您可以在
WHERE
子句中使用核心日期欄位,但不必在SELECT
子句中加入該欄位。如有需要,您也可以在兩個子句中加入這個欄位。此查詢範例會在日期範圍內按廣告活動名稱傳回
clicks
指標。請注意,segments.date
不包含在SELECT
子句中。SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
如果您在
SELECT
子句中加入核心日期欄位,則必須在WHERE
子句中指定有限的日期或日期範圍。SELECT
和WHERE
子句中指定的欄位不必相符。此查詢範例會傳回
clicks
指標,在日期範圍內每一天都按廣告活動名稱區隔。SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
ISO 8601 日期
您可以使用 YYYY-MM-DD
(ISO 8601) 格式指定日期和日期範圍,例如:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
對於需要時間範圍 (segments.week
、segments.month
、segments.quarter
) 的核心日期區隔,您可以將 =
運算子與時間範圍的第一天搭配使用,例如:
WHERE segments.month = '2022-06-01'
預先定義的日期
您也可以使用下列預先定義的日期和日期範圍:
預先定義的日期 | |
---|---|
TODAY |
僅限今天。 |
YESTERDAY |
僅限昨天。 |
LAST_7_DAYS |
過去 7 天 (不含今天)。 |
LAST_BUSINESS_WEEK |
前 5 天工作週 (週一至週五)。 |
THIS_MONTH |
當月所有天數。 |
LAST_MONTH |
上個月中的所有日子。 |
LAST_14_DAYS |
過去 14 天 (不含今天)。 |
LAST_30_DAYS |
過去 30 天 (不含今天)。 |
THIS_WEEK_SUN_TODAY |
介於前週日和當天之間的時段。 |
THIS_WEEK_MON_TODAY |
從前週一到當天之間的時段。 |
LAST_WEEK_SUN_SAT |
自上週日起的 7 天期間。 |
LAST_WEEK_MON_SUN |
從上週一開始的 7 天期間。 |
示例:
WHERE segments.date DURING LAST_30_DAYS
零指標
執行查詢時,您可能會發現某些實體的指標值為零。瞭解如何處理查詢中的零指標。
UNKNOWN 列舉類型
如果以 UNKNOWN
列舉資料類型傳回資源,表示 API 版本並未完整支援該類型。這些資源可能已透過其他介面建立。舉例來說,Search Ads 360 使用者介面導入新的廣告活動或廣告,但您要查詢的 API 版本尚未支援該廣告活動或廣告。
當資源具有 UNKNOWN
類型時,您仍然可以選取指標,但必須注意下列事項:
- 之後可能會支援具有
UNKNOWN
類型的資源,但它可能會無限期維持UNKNOWN
狀態。 - 類型為
UNKNOWN
的新物件隨時可能出現。由於列舉值已可供使用,因此這些物件具有回溯相容性。每當有這項異動可用,我們就會引進資源,讓您可準確檢視帳戶。當系統透過其他介面在您的帳戶中出現新活動,或是系統不再正式支援某項資源時,就可能顯示UNKNOWN
資源。 UNKNOWN
資源可能會附加詳細指標供您查詢。UNKNOWN
的資源通常會在 Search Ads 360 使用者介面中完整顯示。