GoogleAdsService
是 Google Ads API 的统一对象检索和报告服务。该服务提供以下方法来执行以下操作:
- 检索对象的特定属性。
- 根据日期范围检索对象的效果指标。
- 根据对象的属性对对象进行排序。
- 使用条件来指明您希望在响应中返回哪些对象。
- 限制返回的对象数量。
GoogleAdsService
可以通过两种方式返回结果:
GoogleAdsService.SearchStream
在单个流式响应中返回所有行,这对于大型(超过 10,000 行)结果集的效率更高。如果您的批处理应用希望尽可能快地下载数据,那么这种方法可能更合适。GoogleAdsService.Search
将大型响应分解为易于管理的结果页面。如果您的交互式应用一次显示一页结果,这种方法可能更合适。
详细了解分页与流式传输。
发出请求
搜索方法需要 SearchGoogleAdsRequest
,它由以下属性组成:
customer_id
- Google Ads 查询语言
query
,用于指示要查询的资源、要检索的属性、细分和指标,以及用于限制返回哪些对象的条件 - (仅限
GoogleAdsService.Search
)一个page_size
,用于指示使用分页时单个响应中要返回的对象数量。 - (仅限
GoogleAdsService.Search
)可选page_token
,用于在使用分页时检索下一批结果。
如需详细了解 Google Ads 查询语言,请参阅 Google Ads 查询语言指南。
处理响应
GoogleAdsService
会返回 GoogleAdsRow
对象的列表。
每个 GoogleAdsRow
表示查询返回的对象,由一组根据 SELECT
子句中请求的字段填充的属性组成。对于响应中的 GoogleAdsRow
对象,系统不会填充 SELECT
子句中未包含的属性。
例如,虽然 ad_group_criterion
具有 status
属性,但 SELECT
子句不包含 ad_group_criterion.status
的查询的响应不会填充该行 ad_group_criterion
属性的 status
字段。同样,如果 SELECT
子句不包含来自 campaign
资源的任何字段,系统也不会填充该行的 campaign
属性。
每个 GoogleAdsRow
可以具有与同一结果集中另一行不同的属性和指标;因此,这些行应作为对象查看,而不是表中的固定行。
UNKNOWN 枚举类型
该 API 版本不完全支持使用 UNKNOWN
类型返回的资源。这些资源可以通过其他界面(例如 Google Ads 界面)创建。您可以在资源的类型为 UNKNOWN
时选择指标,但无法通过 API 更改资源。例如,界面中引入了新的广告系列或广告,但您正在查询的 API 版本不支持此类广告系列或广告。
请注意以下几点:
- 具有
UNKNOWN
类型的资源以后可以受支持,也可以无限期保持UNKNOWN
状态。 - 类型为
UNKNOWN
的新对象可以随时出现。这些对象向后兼容,因为枚举值已经可用。这项变更会即时提供可用的资源,以便您准确了解自己的帐号。UNKNOWN
资源可能是由于您的帐号中通过其他接口进行了新活动,或某项资源不再受支持。 UNKNOWN
资源可能附加了可查询的详细指标。UNKNOWN
资源通常在 Google Ads 界面中完全可见。UNKNOWN
资源通常无法更改。
分割
对于以下各项的每种组合,响应都会包含一个 GoogleAdsRow
:
FROM
子句中指定的主要资源的实例- 每个选定
segment
字段的值
例如,对于选择 FROM campaign
并且在 SELECT
子句中包含 segments.ad_network_type
和 segments.date
的查询,其响应将针对以下内容的每种组合包含一行:
campaign
segments.ad_network_type
segments.date
系统会按主要资源的每个实例(而不是各个选定字段的值)对结果进行隐式细分。例如,
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
会导致每个 campaign 输出一行结果,而不是 campaign.status
字段的每个不同值生成一行。