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

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

在 Search Ads 360 Reporting API 中建立搜尋報表

請參閱下列各節，瞭解如何在 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 通常可提供更佳效能，因為它可省去要求個別網頁所需的網路往返時間。建議您將 SearchStream 用於所有資料列超過 10,000 列的報表。對於較小報表 (少於 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 介面。

這項要求包含 HTTP POST，可傳送至下列任一網址的 Search Ads 360 Reporting API 伺服器：

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

以下是 searchStream 報表定義的完整範例，該定義已在 HTTP POST 要求中封裝：

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 子句中的屬性，不會填入回應中的物件。

舉例來說，下列查詢會在每個 SearchAds360Row 物件中只填入 campaign.id、campaign.name 和 campaign.status。其他屬性 (例如 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 子句中使用資源，可以使用「是/否」下拉式選單，篩除無法使用的區隔。

指標欄

並非所有指標欄位都能與特定資源搭配使用。

「指標」欄會列出 metrics 欄位，您可以在相同的 SELECT 子句中使用這些欄位，做為資源的欄位。每個欄位都會連結至該欄位的完整詳細資料，包括說明、類別、資料類型、類型網址，以及可篩選、可選取、可排序和重複設定。如果您在 FROM 子句中使用資源，請使用「是/否」下拉式選單，篩除無法使用的指標。

分割資源

某些資源含有可用於區隔資源欄位的欄位，您可以在資源位於 FROM 子句時選取這些欄位。舉例來說，如果您選取 campaign 資源欄位 (例如 campaign.name)，在 FROM 子句中使用 campaign_budget 時，系統會自動傳回並區隔 campaign.resource_name，因為 campaign 是 campaign_budget 的區隔資源。

「區隔資源」部分會列出可用的區隔資源。並非所有資源都有區隔資源。

可選取的

部分 segments 欄位與其他資源、區隔和指標不相容。

segments 頁面包含每個 segments 欄位的 Selectable with 展開式選單，其中列出所有相容的資源欄位、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 子句中指定多個區隔。回應會針對 FROM 子句中指定的主要資源的每個例項組合，以及每個所選 segment 欄位的值，包含一個 SearchAds360Row 物件。

舉例來說，下列查詢會針對 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

核心日期區隔欄位是一般規則的例外狀況，也就是說，您無法在 WHERE 子句中使用區隔欄位，除非您同時在 SELECT 子句中加入該欄位。詳情請參閱「禁止篩選」。

核心日期區隔規則：

您可以在 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 列舉資料類型傳回，表示 API 版本不完全支援該類型。這些資源可能已透過其他介面建立。舉例來說，Search Ads 360 UI 中推出了新廣告活動或廣告，但您要查詢的 API 版本尚未支援。

資源類型為 UNKNOWN 時，您仍可選取指標，但請注意下列事項：

日後可能會支援 UNKNOWN 類型的資源，但可能會無限期保留 UNKNOWN。
類型為 UNKNOWN 的新物件隨時都可能出現。這些物件已提供列舉值，因此可向下相容。我們會在推出這項異動時提供相關資源，讓您能正確掌握帳戶狀況。UNKNOWN 資源可能會因為帳戶透過其他介面產生新的活動，或是資源不再正式支援而顯示。
UNKNOWN 資源可能會附加您可以查詢的詳細指標。
UNKNOWN 資源通常會完整顯示在 Search Ads 360 UI 中。