Google Ads 界面中的报告
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本指南将 Google Ads 界面中报告的概念和命名惯例与您可以使用 Google Ads 查询语言 (GAQL) 和 Google Ads API 生成的报告相关联。
常见界面术语
下表总结了界面中使用的一些常用术语及其与 Google Ads 查询语言 (GAQL) 的对应关系。
列

界面中的列相当于 GAQL 中的资源字段、细分字段和指标。
过滤
您可以过滤和整理报告中的数据。
日期范围
Google Ads 界面中有一个表格,用于显示账号统计信息,还有一个下拉菜单,用于控制这些统计信息的日期范围。

在 GAQL 中,您可以通过在 GAQL 查询的 WHERE 子句中过滤 segments.date
来实现相同的控制。
过滤条件

界面中的过滤条件相当于 GAQL 的 WHERE 子句中的一个或多个条件。
细分

如需查看更详细的统计信息,请按细分受众群拆分数据。例如,假设您想分别查看 Google 搜索网络和 Google 展示广告网络的展示次数。在这种情况下,请按广告资源网细分报告。如需了解如何在 SELECT 子句中添加细分字段,请参阅细分。
您可以使用每个数据表格底部提供的控件在界面中浏览报告,这些控件可让您切换页面,并从一组预定义的大小中选择要显示的结果数量。

通过 next_page_token
使用 GoogleAdsService.Search
检索报告时,可以对结果进行分页。如需提取整个结果集而不进行任何分页,请使用 GoogleAdsService.SearchStream
。
对结果排序
在界面中,您可以通过选择列来对结果进行排序。

在 GAQL 中,您可以使用 ORDER BY 子句和 LIMIT 子句对查询结果进行排序。
在界面中,报告可以下载为各种格式,例如 CSV、TSV 或 XML。

该 API 不直接支持输出中的不同格式,因此您必须执行一些后处理。请参阅此代码示例,了解如何在客户端中实现 CSV 格式设置。
定期生成报告并通过电子邮件发送
您可以在界面中安排报告的生成时间和通过电子邮件发送报告,但 API 不支持这些功能。
预定义的报告
您可以在 Google Ads 界面中创建预定义报告的列表。

下面列出了基本预定义报告及其对应的 GAQL 资源名称。
以前面表格中的示例为例,您可以使用以下 GAQL 生成账号报告:
SELECT
customer.descriptive_name,
customer.id,
metrics.clicks,
metrics.impressions,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros,
metrics.absolute_top_impression_percentage,
metrics.top_impression_percentage,
metrics.average_cpm
FROM customer
WHERE segments.date DURING LAST_7_DAYS
常见差异
将界面报告与 API 报告进行比较时,最常见的差异之一是界面会隐式过滤掉已移除的实体,而 API 不会。
为了复制默认界面视图,您需要添加一个过滤条件(通常使用 status
字段)来排除已移除的行。例如:
SELECT campaign.name
FROM campaign
WHERE campaign.status != "REMOVED"
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-27。
[null,null,["最后更新时间 (UTC):2025-08-27。"],[[["\u003cp\u003eThis guide explains how to generate reports using the Google Ads Query Language (GAQL) and the Google Ads API, mirroring the functionality of reports within the Google Ads UI.\u003c/p\u003e\n"],["\u003cp\u003eIt provides mappings between common UI terms like Columns, Filters, and Segmentation to their corresponding GAQL equivalents, enabling users to construct queries effectively.\u003c/p\u003e\n"],["\u003cp\u003eThe document details how to achieve UI functionalities like filtering by date range, pagination, ordering results, and accessing predefined reports using GAQL.\u003c/p\u003e\n"],["\u003cp\u003eUsers are made aware of common differences between UI and API reports, such as the UI's implicit filtering of removed entities, and are provided with guidance on replicating UI behavior in their queries.\u003c/p\u003e\n"],["\u003cp\u003eWhile functionalities like downloading in various formats and scheduling/emailing are available in the UI, they require additional implementation or are not directly supported within the API.\u003c/p\u003e\n"]]],[],null,["# Reports in the Google Ads UI\n\nThis guide maps the concepts and naming conventions for reports in the Google Ads UI\nto the reports that you can generate using the Google Ads Query Language (GAQL) and\nthe Google Ads API.\n\nCommon UI terms\n---------------\n\nThe following table summarizes some of the common terms used in the UI and their\nmappings to the [Google Ads Query Language (GAQL)](/google-ads/api/docs/query/overview).\n\n| UI | GAQL |\n| [Columns](/google-ads/api/docs/reporting/uireports#columns) | Any resource, segment field or metric in the [SELECT clause](/google-ads/api/docs/query/structure#select) of a GAQL query. |\n| [Date Range](/google-ads/api/docs/reporting/uireports#filtering) | Date ranges map to a [WHERE clause](/google-ads/api/docs/query/structure#where) filtering on `segments.date`. |\n| [Filters](/google-ads/api/docs/reporting/uireports#filtering) | One or more conditions in the [WHERE clause](/google-ads/api/docs/query/structure#where). |\n| [Segment fields](/google-ads/api/docs/reporting/uireports#segmentation) | Apply [segmentation](#segmentation) by including segment fields in your GAQL query. |\n| [Pagination](/google-ads/api/docs/reporting/uireports#pagination) | [Paging](/google-ads/api/docs/reporting/paging) breaks up the result set of the query into multiple pages. |\n|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|\n\n### Columns\n\nColumns in the UI are equivalent to\n[Resource fields](/google-ads/api/docs/query/overview#query_for_resource_attributes),\n[Segment fields](/google-ads/api/docs/reporting/segmentation), and\n[Metrics](/google-ads/api/docs/query/overview#query_for_metrics) in GAQL.\n\n### Filtering\n\nYou can filter and organize the data in your reports.\n\n#### Date ranges\n\nThe Google Ads UI has a table displaying account statistics, and a drop-down menu to\ncontrol the date range of these statistics.\n\nYou have the same control in GAQL by filtering on\n[`segments.date`](/google-ads/api/docs/query/date-ranges) in the WHERE clause of a GAQL\nquery.\n\n#### Filters\n\nFilters in the UI are equivalent to one or more conditions in the\n[WHERE clause](/google-ads/api/docs/query/structure#where) of GAQL.\n\n### Segmentation\n\nFor more detailed statistics, split the data by segments. For example, suppose\nyou want to see the number of impressions specific to the Google Search Network\nseparately from the Google Display Network. In that case, segment your report by\nnetwork. See [Segmentation](/google-ads/api/docs/reporting/segmentation) on how to include\nsegment fields in the SELECT clause.\n\n### Pagination\n\nNavigate through your reports in the UI using the controls available at the\nbottom of each table of data that let you switch pages and select the number of\nresults to display from a defined set of sizes.\n\nPaging through results is available when retrieving reports with\n[`GoogleAdsService.Search`](/google-ads/api/reference/rpc/v21/GoogleAdsService/Search) through\n[`next_page_token`](/google-ads/api/docs/reporting/paging). To fetch the entire result set\nwithout any pagination, use\n[`GoogleAdsService.SearchStream`](/google-ads/api/docs/reporting/streaming).\n\n### Order results\n\nIn the UI, you can order results by selecting a column.\n\nIn GAQL, you can use the\n[ORDER BY clause](/google-ads/api/docs/query/ordering-limiting#order_results) and\n[LIMIT clause](/google-ads/api/docs/query/ordering-limiting#limit_the_number_of_results)\nto order your query result.\n\nDownload formats\n----------------\n\nIn the UI, reports can be downloaded in various formats, such as CSV, TSV, or\nXML.\n\nThe API doesn't directly support different formats in its output, so you have to\nperform some post-processing. See this\n[code example](/google-ads/api/samples/campaign-report-to-csv) that shows how\nto implement CSV formatting in a client.\n\nSchedule and email reports\n--------------------------\n\nYou can schedule and email a report from the UI, but these features are not\nsupported in the API.\n\nPredefined reports\n------------------\n\nYou can create a list of predefined reports in the Google Ads UI.\n\nHere's a list of the basic predefined reports and their matching GAQL Resource\nName.\n\n| Basic Predefined Reports | GAQL Resource Name (Specify in the [FROM clause](/google-ads/api/docs/query/structure#from)) |\n|----------------------------|----------------------------------------------------------------------------------------------|\n| Account | [customer](/google-ads/api/fields/v21/customer) |\n| Campaign, Campaign details | [campaign](/google-ads/api/fields/v21/campaign) |\n| Ad group, Ad group details | [ad_group](/google-ads/api/fields/v21/ad_group) |\n| Ad, Final URL | [ad_group_ad](/google-ads/api/fields/v21/ad_group_ad) |\n| Search keyword | [keyword_view](/google-ads/api/fields/v21/keyword_view) |\n| Search terms | [search_term_view](/google-ads/api/fields/v21/search_term_view) |\n| Paid and organic | [paid_organic_search_term_view](/google-ads/api/fields/v21/paid_organic_search_term_view) |\n| Landing page | [landing_page_view](/google-ads/api/fields/v21/landing_page_view) |\n| Expanded Landing page | [expanded_landing_page_view](/google-ads/api/fields/v21/expanded_landing_page_view) |\n\nAs an example from the preceding table, you can use the following GAQL to\ngenerate the Account report: \n\n SELECT\n customer.descriptive_name,\n customer.id,\n metrics.clicks,\n metrics.impressions,\n metrics.ctr,\n metrics.average_cpc,\n metrics.cost_micros,\n metrics.absolute_top_impression_percentage,\n metrics.top_impression_percentage,\n metrics.average_cpm\n FROM customer\n WHERE segments.date DURING LAST_7_DAYS\n\nCommon differences\n------------------\n\nWhen comparing UI reports to API reports, one of the most common differences is\nthat the UI implicitly filters out removed entities, whereas the API does not.\n\nIn order to replicate a default UI view, you need to add a filter, typically\nusing a `status` field, to exclude removed rows. For example: \n\n SELECT campaign.name\n FROM campaign\n WHERE campaign.status != \"REMOVED\""]]