检索对象

GoogleAdsService 是 Google Ads API 的统一对象检索和报告服务。该服务具有以下方法：

  • 检索对象的特定属性。
  • 根据日期范围检索对象的性能指标。
  • 根据对象的属性对对象进行排序。
  • 使用条件来指明您希望在响应中返回哪些对象。
  • 限制返回的对象数量。

GoogleAdsService 可以通过以下两种方式返回结果：

  • GoogleAdsService.SearchStream 以单个流式响应返回所有行，对于大型（超过 10,000 行）结果集来说，这种方式更高效。如果您的应用下载完整的结果集或以流的形式处理行，建议使用此选项。
  • GoogleAdsService.Search 将大型响应分解为可管理的搜索结果页面。如果您的互动式应用一次显示一页结果，此属性会非常有用。

详细了解分页与流式传输。

发出请求

GoogleAdsService.SearchStream 需要 SearchGoogleAdsStreamRequest，而 GoogleAdsService.Search 需要 SearchGoogleAdsRequest。这两种请求类型都包含以下内容：

  • customer_id
  • 一种 Google Ads 查询语言 query，用于指示要查询的资源、要检索的属性、细分和指标，以及用于限制返回哪些对象的条件

根据方法，请求还支持特定于方法的字段：

  • SearchGoogleAdsStreamRequest（仅限 SearchStream）：
  • SearchGoogleAdsRequest（仅限 Search）：
    • 一个可选的 page_token，用于在使用分页时检索下一批结果（page_size 固定为 10,000 行；在请求中设置 page_size 会引发 RequestError.PAGE_SIZE_NOT_SUPPORTED 错误）
    • 用于配置 return_summary_row、return_total_results_count 和 omit_results 的可选 search_settings 消息
    • 一个可选的 validate_only 布尔值，用于在不执行查询的情况下验证查询

如需详细了解 Google Ads 查询语言，请参阅 Google Ads 查询语言指南。

处理回答

GoogleAdsService 会返回一个 GoogleAdsRow 对象列表（在流式 SearchGoogleAdsStreamResponse 批次中或在分页 SearchGoogleAdsResponse 中）。

每个 GoogleAdsRow 都表示查询返回的对象，并包含一组根据 SELECT 子句中请求的字段填充的属性。SELECT 子句中未包含的属性不会填充到响应中的 GoogleAdsRow 对象中。

例如，虽然 ad_group_criterion 具有 status 属性，但在 SELECT 子句不包含 ad_group_criterion.status 的查询的响应中，相应行的 ad_group_criterion 属性的 status 字段不会填充。同样，如果 SELECT 子句不包含 campaign 资源中的任何字段，则不会填充相应行的 campaign 属性。

每个 GoogleAdsRow 可以具有与同一结果集中的另一行不同的属性和指标；因此，应将这些行视为对象，而不是表的固定行。

UNKNOWN 和 UNSPECIFIED 枚举类型

如果返回的资源具有 UNKNOWN 的枚举值，则表示相应 API 版本未完全支持该资源；而 UNSPECIFIED 表示枚举字段未设置或未在 SELECT 子句中请求。具有 UNKNOWN 枚举值的资源可能是通过其他界面（例如 Google Ads 界面）创建的。当资源类型为 UNKNOWN 时，您可以选择指标，但无法通过 API 更改资源。例如，界面中提供的广告系列或广告类型在您查询的 API 版本中不受支持。

请注意以下几点：

  • 具有 UNKNOWN 类型的资源可能会在后续 API 版本中受支持，也可能会无限期保持 UNKNOWN 状态。
  • 类型为 UNKNOWN 的新对象可以随时出现。这些对象是向后兼容的，因为 API 中的每个枚举都存在 UNKNOWN 枚举值。返回的资源带有 UNKNOWN，以便您准确了解账号的总体效果指标。
  • UNKNOWN 资源可以附加可查询的详细指标。
  • UNKNOWN资源通常会在 Google Ads 界面中完全显示。
  • 通常无法通过 API 更改 UNKNOWN 资源。

分割

响应包含一个 GoogleAdsRow，对应于以下各项的每种组合：

  • FROM 子句中指定的主要资源的实例
  • 每个所选 segments 字段的值

例如，如果查询选择 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.status 字段的每个不同值占一行。

上一页
更改对象
下一页
资源元数据