检索对象

目标： 了解如何使用 GoogleAdsService 检索对象和效果统计信息。如需了解报告概念，请参阅报告指南。

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

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

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

• GoogleAdsService.SearchStream 会在单个流式响应中返回所有行，这对于大型（超过 10,000 行）结果集更高效。如果您的应用下载完整结果集或以流的形式处理行，建议您使用此方法。
• GoogleAdsService.Search 会将大型响应拆分为可管理的结果页面。如果您的交互式应用一次显示一页结果，则此功能非常有用。

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

发出请求

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

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

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

• SearchGoogleAdsStreamRequest（仅限 SearchStream）：
  • 一个可选的 summary_row_setting，用于请求包含汇总指标的摘要行
• 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 界面中完全可见。
• UNKNOWN 资源通常无法通过 API 进行更改。

分割

对于以下各项的每种组合，响应都包含一个 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 字段的每个不同值生成一行。

注意： 不同 API 版本的细分受众群可用性可能有所不同。例如，AdGroupAsset、CampaignAsset 和 CustomerAsset 上的 segments.click_type 以及 campaign_budget 上的 segments.ad_sub_network_type 只能在 v23 及更低版本中选择；PerformanceMaxPlacementView 上的 segments.ad_network_type 在 v24 及更高版本中可用；segments.ad_sub_format_type 和 segments.loyalty_membership 在 v25 及更高版本中可用；segments.search_lift_keyword_bundle 和 segments.search_property 在 v26 及更高版本中可用。使用 GoogleAdsFieldService 验证您要查询的 API 版本的细分兼容性。