在 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 介面。

這項要求內含向 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 使用者介面中完整顯示。