检索对象
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
GoogleAdsService
是 Google Ads API 的统一对象检索和报告服务。该服务具有以下方法:
- 检索对象的特定属性。
- 根据日期范围检索对象的效果指标。
- 根据对象的属性对对象进行排序。
- 使用条件指示要在响应中返回的对象。
- 限制返回的对象数量。
GoogleAdsService
可以通过两种方式返回结果:
详细了解分页与流式传输。
发出请求
搜索方法需要 SearchGoogleAdsRequest
,其中包含以下属性:
customer_id
- Google Ads 查询语言
query
,用于指示要查询的资源,要检索的属性、细分和指标,以及用于限制返回哪些对象的条件
- (仅限
GoogleAdsService.Search
)可选的 page_token
,用于在使用分页时检索下一批结果。
如需详细了解 Google Ads 查询语言,请参阅 Google Ads 查询语言指南。
处理回答
GoogleAdsService
会返回一个 GoogleAdsRow
对象列表。
每个 GoogleAdsRow
都表示相关查询所返回的对象,由一组根据 SELECT
子句中请求的字段填充的属性组成。如果属性未包含在 SELECT
子句中,则不会在响应的 GoogleAdsRow
对象中填充相应属性。
例如,虽然 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
,那么该查询的响应将包含一个 GoogleAdsRow 行,对应于以下各项的每种组合:
campaign
segments.ad_network_type
segments.date
系统会按主要资源的每个实例(而不是各个选定字段的值)对结果进行隐式细分。例如,
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
执行上述代码后,会按每个 campaign 输出一行结果,而不是 campaign.status
字段的每个不同的值输出一行结果。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-26。
[null,null,["最后更新时间 (UTC):2025-08-26。"],[[["\u003cp\u003eGoogle Ads API's \u003ccode\u003eGoogleAdsService\u003c/code\u003e enables retrieval of object attributes, performance stats, and implements ordering, conditions, and limits for streamlined data access.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGoogleAdsService\u003c/code\u003e offers two response methods: \u003ccode\u003eSearchStream\u003c/code\u003e for efficient handling of large datasets and \u003ccode\u003eSearch\u003c/code\u003e for manageable, paginated results.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGoogleAdsService.Search\u003c/code\u003e requests require \u003ccode\u003ecustomer_id\u003c/code\u003e, Google Ads Query Language \u003ccode\u003equery\u003c/code\u003e, and optional pagination parameters (\u003ccode\u003epage_size\u003c/code\u003e, \u003ccode\u003epage_token\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003eResponses comprise \u003ccode\u003eGoogleAdsRow\u003c/code\u003e objects, reflecting queried object attributes and metrics as specified in the \u003ccode\u003eSELECT\u003c/code\u003e clause.\u003c/p\u003e\n"],["\u003cp\u003eResources returned with an \u003ccode\u003eUNKNOWN\u003c/code\u003e type are not fully supported in that API version, might have been created through other interfaces, and are generally not mutable.\u003c/p\u003e\n"]]],[],null,["# Retrieving objects\n\n| **Objective:** Understand how to retrieve objects and performance stats using [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService). For reporting concepts, see the [reporting guides](/google-ads/api/docs/reporting/overview).\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) is the unified object\nretrieval and reporting service of the Google Ads API. The service has methods that:\n\n- Retrieve specific attributes of objects.\n- Retrieve performance metrics for objects based on a date range.\n- Order objects based on their attributes.\n- Use conditions to indicate which objects you want returned in the response.\n- Limit the number of objects returned.\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) can return results in\ntwo ways:\n\n- [`GoogleAdsService.SearchStream`](/google-ads/api/reference/rpc/v21/GoogleAdsService/SearchStream) returns all rows in a single streaming response which is more efficient for large (greater than 10,000 rows) result sets. This might be more appropriate if your batch application wants to download as much data as fast as possible.\n- [`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) breaks up large responses into manageable pages of results. This could be more appropriate if your interactive application displays a page of results at a time.\n\nLearn more about [paging versus streaming](/google-ads/api/docs/reporting/streaming).\n\nMake a request\n--------------\n\nThe search method requires a\n[`SearchGoogleAdsRequest`](/google-ads/api/reference/rpc/v21/SearchGoogleAdsRequest), which consists\nof the following attributes:\n\n- A `customer_id`\n- A Google Ads Query Language `query` that indicates which resource to query, the attributes, segments, and metrics to retrieve, and the conditions to use to restrict which objects are returned\n- ([`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) only) An optional `page_token` to retrieve the next batch of results when using [paging](/google-ads/api/docs/reporting/paging).\n\nFor more information on the Google Ads Query Language, check out the [Google Ads Query Language\nguide](/google-ads/api/docs/query/overview).\n\nProcess a response\n------------------\n\nThe [`GoogleAdsService`](/google-ads/api/reference/rpc/v21/GoogleAdsService) returns a list of\n[`GoogleAdsRow`](/google-ads/api/reference/rpc/v21/GoogleAdsRow) objects.\n\nEach `GoogleAdsRow` represents an object returned by a query, and consists of a\nset of attributes that are populated based on the fields requested in the\n`SELECT` clause. Attributes not included in the `SELECT` clause are not\npopulated on the `GoogleAdsRow` objects in the response.\n\nFor example, although an `ad_group_criterion` has a `status` attribute, the\n`status` field of the row's `ad_group_criterion` attribute is not populated in a\nresponse for a query where the `SELECT` clause does not include\n`ad_group_criterion.status`. Similarly, the `campaign` attribute of the row is\nnot populated if the `SELECT` clause does not include any fields from the\n`campaign` resource.\n\nEach `GoogleAdsRow` can have different attributes and metrics from another row\nin the same result set; so the rows should be viewed as objects rather than\nfixed rows of a table.\n\nUNKNOWN enum types\n------------------\n\nResources that are returned with a type of `UNKNOWN` are not fully supported in\nthat API version. These resources could have been created through other\ninterfaces such as the Google Ads UI. You can select metrics when a resource has a\ntype of `UNKNOWN`, but you cannot mutate the resource through the API. An\nexample of this would be a new campaign or ad being introduced in the UI, but\nnot supported in the API version you are querying.\n\nHere are some considerations to keep in mind:\n\n- A resource with an `UNKNOWN` type can be supported later or stay `UNKNOWN` indefinitely.\n- New objects with type `UNKNOWN` can appear at any time. These objects are backward compatible because the enum value is already available. Resources are introduced with this change as they're available so that you have an accurate view of your account. The `UNKNOWN` resource can appear due to new activities in your account through other interfaces, or when a resource is no longer supported.\n- `UNKNOWN` resources can have detailed metrics attached to them that are queryable.\n- `UNKNOWN` resources are typically fully visible in the Google Ads UI.\n- `UNKNOWN` resources generally cannot be mutated.\n\nSegmentation\n------------\n\nThe response would contain one `GoogleAdsRow` for each combination of the\nfollowing:\n\n- Instance of the main resource specified in the `FROM` clause\n- Value of each selected `segment` field\n\nFor example, the response for a query that selects `FROM campaign` and has\n`segments.ad_network_type` and `segments.date` in the `SELECT` clause would\ncontain one row for each combination of the following:\n\n- `campaign`\n- `segments.ad_network_type`\n- `segments.date`\n\nResults are implicitly segmented by each instance of the main resource, not by\nthe values of the individual fields selected. For example, \n\n SELECT campaign.status, metrics.impressions\n FROM campaign\n WHERE segments.date DURING LAST_14_DAYS\n\nresults in one row per **campaign** , not one row per distinct value of the\n`campaign.status` field."]]