新版 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 通常可提供更佳效能，因為它可省去要求個別網頁所需的網路往返時間。如果報表有超過 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 介面。

這項要求包含 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

以下是 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 等欄位。

「已指派資源」區段會列出可用的已指派資源。並非所有資源都有歸屬資源。

資源欄位欄

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

「區段」欄

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

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

指標欄

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

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

區隔資源

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

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

可選取的項目

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

segments 頁面為每個 segments 欄位提供「可選取的項目」，且該欄位會列出所有可納入 SELECT 子句的相容資源欄位、metrics 欄位，以及其他 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 物件，其中包含您在 FROM 子句中指定的主要資源「例項」，以及每個所選 segment 欄位的「值」。

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

如果資源是使用 UNKNOWN 列舉資料類型傳回，表示 API 版本不完全支援該類型。這些資源可能已透過其他介面建立。舉例來說，Search Ads 360 UI 中推出了新廣告活動或廣告，但您要查詢的 API 版本尚未支援。

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

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