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

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

請參閱下方各節，瞭解如何透過 Search Ads 360 報表 API 建立搜尋報表。

搜尋服務

Search Ads 360 Reporting API 提供專門的搜尋和報表服務。

SearchAds360Service 是統一的物件擷取和報表服務，提供兩種搜尋方法：SearchStream 和 Search。搜尋內容會以查詢字串的形式傳遞，並以 Search Ads 360 查詢語言編寫。您可以定義查詢，以便：

擷取物件的特定屬性。
根據日期範圍擷取物件的成效指標。
根據物件的屬性排序。
使用指定要傳回哪些物件的條件來篩選結果
限制傳回的物件數量。

這兩種搜尋方法都會傳回符合查詢條件的所有資料列。舉例來說，當您擷取 campaign.id、campaign.name 和 metrics.clicks 時，API 會傳回 SearchAds360Row，其中包含已設定 id 和 name 欄位的廣告活動物件，以及已設定 clicks 欄位的 metrics 物件。

搜尋方法

SearchStream

傳送單一要求，並與 Search Ads 360 報表 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 子句未包含的屬性。

舉例來說，下列查詢只會填入每個 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 等欄位。

「已歸因資源」部分會列出可用的已歸因資源。並非所有資源都有歸因資源。

資源欄位欄

資源的所有欄位都會納入「資源欄位」欄。每個資源欄位都會連結至欄位的詳細資料，包括說明、類別、資料類型、類型網址，以及可篩選、可選取、可排序和重複的設定。

區隔資料欄

並非所有區隔欄位都能與指定資源搭配選取。

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

指標欄

並非所有指標欄位都能與指定資源搭配選取。

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

區隔資源

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

「Segmenting resources」(區隔資源) 區段會列出可用的區隔資源。並非所有資源都有區隔資源。

可選取

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

「segments」segments」頁面會針對每個 segments 欄位顯示可選取的展開式，列出所有相容的資源欄位、metrics 欄位，以及可納入 SELECT 子句的其他 segments 欄位。

區隔

您可以在查詢的 SELECT 子句中加入 segments.FIELD_NAME 欄位，將搜尋結果區隔。

舉例來說，在下列查詢中，segments.device 會產生一份報表，其中包含 impressions 的每個裝置資料列，以及 FROM 子句中指定的資源。

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

核心日期區隔欄位是例外狀況，一般來說，除非您也在 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 使用者介面中。