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

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

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

如要瞭解如何在搜尋廣告中建立搜尋報表，請參閱以下各節 360 Reporting API。

Google 搜尋服務

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 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 存取 API

這項要求是由 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。也就是說，您可以在 campaign.id 和 campaign.bidding_strategy_type 中加入在 FROM 子句中使用 ad_group 時，必須執行查詢。

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

資源欄位欄

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

區隔欄

並非所有的區隔欄位都可透過指定的資源選取。

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

指標欄

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

「指標」指標欄列出了metrics您可以在 SELECT 子句當做資源的欄位使用。每個欄位都會連結至完整的欄位詳細資料，包括欄位說明、類別、資料類型、類型「網址」和「可篩選」、「可選取」、「可排序」和「重複」設定如果您是在 FROM 子句中使用資源，並透過「Yes/No」下拉式選單進行以下操作：會濾除不適用的指標

區隔資源

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

「區隔資源」一節會列出可用的區隔資源。非所有資源都有區隔資源

可選取的項目

某些「segments」欄位與其他資源、區隔和指標。

「segments」頁面包含每個 segments 欄位可展開的「可選取」，列出所有相容的資源欄位、metrics 欄位，以及其他 segments 可加入 SELECT 子句中的多個欄位。

區隔

如要區隔搜尋結果，您可以在名稱中加入 segments.FIELD_NAME 欄位改成查詢的 SELECT 子句。

舉例來說，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 子句中指定多個區隔。回應包含一個 SearchAds360Row 物件，而在 FROM 子句中指定的主要資源 instance 和每個所選 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

核心日期區隔欄位屬於您一般規則的例外情況 無法在 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 使用者介面中推出，但 API 版本尚未支援。就能取得更符合需求的結果

資源屬於 UNKNOWN 類型時，您還是可以選取指標，但必須注意以下幾點：

系統之後可能會支援類型為 UNKNOWN 的資源，但可能會繼續保留無限期UNKNOWN。
系統隨時可能會顯示類型為 UNKNOWN 的新物件。這些物件回溯相容，因為列舉值已可用。我們介紹隨時更新資源，確保您能取得正確的帳戶檢視畫面UNKNOWN 資源可能會顯示於您帳戶透過其他介面的活動，或是因為某項資源而產生的活動不再受到正式支援
UNKNOWN 項資源可能已附加詳細指標，你可以。
UNKNOWN 資源通常會完整顯示在 Search Ads 360 使用者介面中。