请阅读下文,了解如何在 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
字段的广告系列对象,以及一个设置了 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
接口。
此请求包含发送到 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 列列出了可在与资源字段相同的
SELECT
子句中使用的segments
字段。每个字段都会链接到有关相应字段的完整详细信息,包括字段说明、类别、数据类型、类型网址,以及可过滤、可选择、可排序和重复设置。如果您在FROM
子句中使用该资源,则可以使用是/否下拉菜单过滤掉不可用的细分。- 指标列
对于给定资源,并非所有指标字段都可供选择。
Metrics 列列出了可在与资源字段相同的
SELECT
子句中使用的metrics
字段。每个字段都会链接到有关相应字段的完整详细信息,包括字段说明、类别、数据类型、类型网址,以及可过滤、可选择、可排序和重复设置。如果您在FROM
子句中使用该资源,请使用是/否下拉列表过滤掉不可用的指标。
- 对资源进行细分
某些资源具有细分资源字段,当资源位于
FROM
子句中时,您可以选择这些字段。例如,如果您选择campaign
资源字段(如campaign.name
),那么当您在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
子句中指定多个细分。对于 FROM
子句中指定的主要资源的实例的每个组合,以及每个选定 segment
字段的 value,在响应中都包含一个 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 枚举类型
如果返回资源时提供的是 UNKNOWN
枚举数据类型,这意味着 API 版本不完全支持该类型。这些资源可能是通过其他接口创建的。例如,Search Ads 360 界面中出现了新的广告系列或广告,但您正在查询的 API 版本还不支持它。
当资源的类型为 UNKNOWN
时,您仍然可以选择指标,但需要注意以下几点:
- 以后可能会支持
UNKNOWN
类型的资源,但它可以无限期地保留UNKNOWN
。 - 类型为
UNKNOWN
的新对象可能会随时出现。这些对象可向后兼容,因为相应的枚举值已经可用。我们在此变更推出后,会及时发布相关资源,以便您准确了解自己的帐号。之所以显示UNKNOWN
资源,可能是因为您的帐号通过其他接口出现了新活动,或者某个资源不再受到正式支持。 UNKNOWN
资源可能附加了详细指标,您可以查询这些指标。- 在 Search Ads 360 界面中,
UNKNOWN
资源通常完全可见。