reportData.query 方法提供了一种同步检索报告数据的方式。与生成基于文件的报告（CSV 或 Excel）的标准 Reports 服务不同，此方法直接在响应中返回结构化 JSON 数据。这样一来，您就不需要预先定义、创建和保存 Report 资源，因此非常适合实时检索和探索数据。
概览
请按照本指南操作，熟悉如何使用此端点查询 Campaign Manager 360 报告数据。
准备请求
构建一个 ReportDataQueryRequest，指定维度、指标、日期范围、过滤条件和排序条件。
REST
{
"body": {
"dateRange": "LAST_7_DAYS",
"dimensionNames": [
"advertiser",
"campaign"
],
"metricNames": [
"impressions",
"clicks"
],
"sortBys": [
{
"name": "clicks",
"sortOrder": "DESCENDING"
}
],
"maxResults": 100
}
}
dateRange- 一个
DateRange对象，用于指定查询的时间段。可以是自定义日期范围，也可以是相对日期范围。 dimensionNames- 要分组的标准维度名称列表。
metricNames- 必需。要纳入的标准指标名称列表。
dimensionFilters- 用于过滤报告数据的 DimensionValue 对象列表。使用此参数可将查询结果限制为特定维度值。
sortBys- 维度或指标的排序配置。每项配置都包含字段名称和排序顺序。
maxResults- 每页返回的最大行数（默认值：
100，最大值：1000）。
分页
maxResults 字段用于控制单个响应中返回的结果数。例如，如果您将 maxResults 设置为 10，则 API 最多会返回 10 个结果。如果符合您请求的结果少于 10 个，API 可能会返回少于 10 个结果。
如果还有其他结果，响应将包含 nextPageToken。如需检索下一页结果，请再次发送同一请求，并将 pageToken 字段设置为此令牌。其他所有请求参数保持不变。
发送请求
向 reportdata/query 端点发送 HTTP POST 请求：
POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query
确保您的请求已通过标准 OAuth 2.0 凭据和必要的范围进行身份验证。如需了解详情，请参阅授权请求。
成功响应
如果查询成功，则会返回一个 HTTP 200 OK 响应，其中包含 columnHeaders、rows 和 totalRow 的 JSON 载荷。
{
"columnHeaders": [
{ "name": "advertiser", "type": "DIMENSION" },
{ "name": "campaign", "type": "DIMENSION" },
{ "name": "impressions", "type": "METRIC" },
{ "name": "clicks", "type": "METRIC" }
],
"rows": [
{
"values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
},
{
"values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
}
],
"totalRow": {
"values": [ "", "", "150831", "422" ]
},
"nextPageToken": "1234567890"
}
columnHeaders- 返回的字段的名称和类型（
DIMENSION或METRIC）。 rows- 包含查询结果的
ReportDataRow对象列表。每行中的字符串值按位置与columnHeaders对齐。 totalRow- 一个汇总行，表示所有匹配指标的总和。无法求和的维度字段和指标（例如覆盖面指标，如
uniqueReachTotalReach）在此行中为空 ("")。 nextPageToken- 一种令牌，用于在后续请求中检索下一页（如果存在其他行）。
延迟和超时
由于这是一个同步端点，因此查询会立即执行，并且数据会直接在响应中返回（最多达到 maxResults 分页限制）。查询的最长执行时间为 60 秒。如果查询超出此限制，API 会终止操作并返回 HTTP 503 Service
Unavailable 错误。
如果您遇到此错误，请尝试缩小日期范围、缩小过滤范围（例如按特定广告客户或广告系列进行过滤），或减少请求的维度和指标数量。或者，使用 reports.run 运行 Report 以异步生成可下载的报告文件。
查询限制和约束
reportdata.query 端点会强制执行多项限制，以确保响应可靠。违反这些限制的请求会被拒绝，并返回 HTTP 400 Bad Request 响应。
日期范围限制
- 对于自定义日期范围，
startDate必须在所请求报告数据类型的数据有效期限内。如需了解详情，请参阅数据可用性。
指标和维度限制
- 必须在
metricNames中提供至少一项指标。 metricNames和dimensionNames列表中的指标和维度必须是唯一的。- 标记为仅下载的指标和维度无法用于这些查询。
配额限制
向此端点发出的请求会消耗以下配额：
- 用户速率限制：每位用户每分钟 120 个请求（2 QPS）
- 每个项目的每日限额：每个项目每天 10,000 次请求
超出这些限制的请求会失败，并显示 HTTP 429 Too Many Requests 错误。如果您翻阅结果，则对新页面的每次请求（使用 pageToken 参数）都将计为单独的查询，并会消耗此配额。