旧版 Search Ads 360 Reporting API 将于 2024 年 6 月 30 日停用。请注意，Search Ads 360 Conversion API 不受影响，并将继续获得支持。所有新的报告开发工作都应使用新版 Search Ads 360 Reporting API。

自 2024 年 4 月起，请求报告时，系统将返回 unsupportedApiVersion 错误。有关详情，请查看此处。

我们还强烈建议您将所有现有的 Search Ads 360 实现迁移到新 API。如需了解详情，请参阅新版 Search Ads 360 Reporting API 的入门指南和迁移指南。

此页面由 Cloud Translation API 翻译。

Reports: request

在报告系统中插入报告请求。立即试用。

请求

HTTP 请求

POST https://www.googleapis.com/doubleclicksearch/v2/reports

授权

此请求需要获得以下范围的授权：

范围
`https://www.googleapis.com/auth/doubleclicksearch`

如需了解详情，请参阅身份验证和授权页面。

请求正文

在请求正文中，请按以下结构提供数据：

{
  "reportScope": {
    "agencyId": long,
    "advertiserId": long,
    "engineAccountId": long,
    "campaignId": long,
    "adGroupId": long,
    "keywordId": long,
    "adId": long
  },
  "reportType": string,
  "columns": [
    {
      "columnName": string,
      "savedColumnName": string,
      "customDimensionName": string,
      "customMetricName": string,
      "headerText": string,
      "startDate": string,
      "endDate": string,
      "groupByColumn": boolean,
      "platformSource": string,
      "productReportPerspective": string
    }
  ],
  "timeRange": {
    "startDate": string,
    "endDate": string,
    "changedMetricsSinceTimestamp": datetime,
    "changedAttributesSinceTimestamp": datetime
  },
  "filters": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "operator": string,
      "values": [
        (value)
      ]
    }
  ],
  "orderBy": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "sortOrder": string
    }
  ],
  "includeDeletedEntities": boolean,
  "includeRemovedEntities": boolean,
  "verifySingleTimeZone": boolean,
  "downloadFormat": string,
  "statisticsCurrency": string,
  "startRow": integer,
  "rowCount": integer,
  "maxRowsPerFile": integer
}

属性名称	值	说明
`reportScope`	`object`	reportScope 是一组 ID，用于确定报告中要返回的实体子集。需要通过代理机构所需的最低范围级别的完整 ID 沿袭。
`reportScope.agencyId`	`long`	DS 代理机构 ID。
`reportScope.advertiserId`	`long`	DS 广告客户 ID。
`reportScope.engineAccountId`	`long`	DS 引擎账号 ID。
`reportScope.campaignId`	`long`	DS 广告系列 ID。
`reportScope.adGroupId`	`long`	DS 广告组 ID。
`reportScope.keywordId`	`long`	DS 关键字 ID。
`reportScope.adId`	`long`	DS 广告 ID。
`reportType`	`string`	确定报告中返回的行的类型。例如，如果您指定 `reportType: keyword`，则报表中的每一行都将包含有关某个关键字的数据。请参阅报告类型参考，了解适用于每种报告类型的列。
`columns[]`	`list`	要包含在报告中的列。这包括 DoubleClick Search 列和已保存的列。对于 DoubleClick Search 列，只有 `columnName` 参数是必需的。对于已保存的列，只有 `savedColumnName` 参数是必需的。不能在同一个 stanza 中同时设置 `columnName` 和 `savedColumnName`。每个请求的最大列数为 300。
`columns[].columnName`	`string`	要包含在报表中的 DoubleClick Search 列的名称。
`columns[].savedColumnName`	`string`	要包含在报告中的已保存列的名称。报表的范围必须为广告客户或更低级别，并且此已保存的列必须已在 DoubleClick Search 界面中创建。
`columns[].headerText`	`string`	用于在报告输出结果中标识此列的文本；如果未指定，则默认为 `columnName` 或 `savedColumnName`。这可用于防止 DoubleClick Search 列与同名的已保存列之间存在冲突。
`columns[].startDate`	`string`	YYYY-MM-DD 格式的包含日期。如果提供此列，则此属性只会覆盖此列的报告的总体时间范围。必须和 `endDate` 一起提供。
`columns[].endDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。如果提供此列，则此属性只会覆盖此列的报告的总体时间范围。必须和 `startDate` 一起提供。
`columns[].groupByColumn`	`boolean`	仅限同步报告。设置为 `true` 即可按此列分组。默认设置为 `false`。
`timeRange`	`object`	如果报告中请求了指标，此参数将用于将指标限制在特定时间范围内。
`timeRange.startDate`	`string`	YYYY-MM-DD 格式的包含日期。
`timeRange.endDate`	`string`	YYYY-MM-DD 格式的包含日期。
`timeRange.changedMetricsSinceTimestamp`	`datetime`	采用 RFC 格式的包含性世界协调时间 (UTC) 时间戳，例如`2013-07-16T10:16:23.555Z`。请参阅其他参考资料，了解已更改的指标报告的运作方式。
`timeRange.changedAttributesSinceTimestamp`	`datetime`	采用 RFC 格式的包含性世界协调时间 (UTC) 时间戳，例如`2013-07-16T10:16:23.555Z`。请参阅其他参考资料，了解已更改的属性报告的运作方式。
`filters[]`	`list`	要应用到报告的过滤条件的列表。每个请求的过滤器数量上限为 300。
`filters[].column`	`nested object`	要对其执行过滤的列。此列可以是 DoubleClick Search 列，也可以是已保存的列。
`filters[].column.columnName`	`string`	要包含在报表中的 DoubleClick Search 列的名称。
`filters[].column.savedColumnName`	`string`	要包含在报告中的已保存列的名称。报表的范围必须为广告客户或更低级别，并且此已保存的列必须已在 DoubleClick Search 界面中创建。
`filters[].operator`	`string`	要在过滤条件中使用的运算符。如需查看可用运算符的列表，请参阅过滤条件参考文档。
`filters[].values[]`	`list`	一个值列表，用于过滤列值。每个请求的过滤条件值数量上限为 300。
`orderBy[]`	`list`	仅限同步报告。定义要对报告行进行排序的列和方向的列表。每个请求的最大订购数为 300。
`orderBy[].column`	`nested object`	要执行排序的列。该列可以是 DoubleClick Search 定义的列，也可以是已保存的列。
`orderBy[].column.columnName`	`string`	要包含在报表中的 DoubleClick Search 列的名称。
`orderBy[].column.savedColumnName`	`string`	要包含在报告中的已保存列的名称。报表的范围必须为广告客户或更低级别，并且此已保存的列必须已在 DoubleClick Search 界面中创建。
`orderBy[].sortOrder`	`string`	排序方向，为 `ascending` 或 `descending`。
`includeDeletedEntities`	`boolean`	确定已移除的实体是否应包含在报告中。默认为 `false`。已弃用，请改用 `includeRemovedEntities`。
`verifySingleTimeZone`	`boolean`	如果为 `true`，则只有在所有请求的统计信息数据都来自同一个时区时，才会创建报告。默认设置为 `false`。
`downloadFormat`	`string`	返回报告时应使用的格式。目前支持 `csv` 或 `tsv`。
`statisticsCurrency`	`string`	指定返回货币时使用的货币。`usdagencyadvertiseraccount`
`startRow`	`integer`	仅限同步报告。要返回的第一行的索引（从零开始）。可接受的值包括`0`到`50000`（含 0 和 50000）。默认值为 `0`。
`rowCount`	`integer`	仅限同步报告。要返回的行数上限；其他行将被舍弃。可接受的值包括`0`到`10000`（含 0 和 50000）。默认值为 `10000`。
`maxRowsPerFile`	`integer`	仅限异步报告。每个报告文件的行数上限。系统会根据此字段将大型报告拆分为多个文件。可接受的值包括`1000000`到`100000000`（含 0 和 50000）。
`includeRemovedEntities`	`boolean`	确定已移除的实体是否应包含在报告中。默认为 `false`。
`columns[].customDimensionName`	`string`	按自定义维度细分报告。报表的范围必须限定为广告客户或更低级别，并且必须已在 DoubleClick Search 中设置自定义维度。DoubleClick Search 中显示的自定义维度名称区分大小写。如果在转化报告中使用，则返回指定转化的指定自定义维度的值（如果已设置）。此列不会细分转化报告。
`columns[].platformSource`	`string`	用于为自定义维度提供数据的平台。可接受的值为“Floodlight”。
`filters[].column.customDimensionName`	`string`	按自定义维度细分报告。报表的范围必须限定为广告客户或更低级别，并且必须已在 DoubleClick Search 中设置自定义维度。DoubleClick Search 中显示的自定义维度名称区分大小写。如果在转化报告中使用，则返回指定转化的指定自定义维度的值（如果已设置）。此列不会细分转化报告。
`filters[].column.headerText`	`string`	用于在报告输出结果中标识此列的文本；如果未指定，则默认为 `columnName` 或 `savedColumnName`。这可用于防止 DoubleClick Search 列与同名的已保存列之间存在冲突。
`filters[].column.startDate`	`string`	YYYY-MM-DD 格式的包含日期。如果提供此列，则此属性只会覆盖此列的报告的总体时间范围。必须和 `endDate` 一起提供。
`filters[].column.endDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。如果提供此列，则此属性只会覆盖此列的报告的总体时间范围。必须和 `startDate` 一起提供。
`filters[].column.groupByColumn`	`boolean`	仅限同步报告。设置为 `true` 即可按此列分组。默认设置为 `false`。
`filters[].column.platformSource`	`string`	用于为自定义维度提供数据的平台。可接受的值为“Floodlight”。
`orderBy[].column.customDimensionName`	`string`	按自定义维度细分报告。报表的范围必须限定为广告客户或更低级别，并且必须已在 DoubleClick Search 中设置自定义维度。DoubleClick Search 中显示的自定义维度名称区分大小写。如果在转化报告中使用，则返回指定转化的指定自定义维度的值（如果已设置）。此列不会细分转化报告。
`orderBy[].column.headerText`	`string`	用于在报告输出结果中标识此列的文本；如果未指定，则默认为 `columnName` 或 `savedColumnName`。这可用于防止 DoubleClick Search 列与同名的已保存列之间存在冲突。
`orderBy[].column.startDate`	`string`	YYYY-MM-DD 格式的包含日期。如果提供此列，则此属性只会覆盖此列的报告的总体时间范围。必须和 `endDate` 一起提供。
`orderBy[].column.endDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。如果提供此列，则此属性只会覆盖此列的报告的总体时间范围。必须和 `startDate` 一起提供。
`orderBy[].column.groupByColumn`	`boolean`	仅限同步报告。设置为 `true` 即可按此列分组。默认设置为 `false`。
`orderBy[].column.platformSource`	`string`	用于为自定义维度提供数据的平台。可接受的值为“Floodlight”。
`columns[].customMetricName`	`string`	要包含在报告中的自定义指标的名称。报表的范围必须限定为广告客户或更低级别，并且必须已在 DoubleClick Search 中设置自定义指标。DoubleClick Search 中显示的自定义指标名称区分大小写。
`filters[].column.customMetricName`	`string`	要包含在报告中的自定义指标的名称。报表的范围必须限定为广告客户或更低级别，并且必须已在 DoubleClick Search 中设置自定义指标。DoubleClick Search 中显示的自定义指标名称区分大小写。
`orderBy[].column.customMetricName`	`string`	要包含在报告中的自定义指标的名称。报表的范围必须限定为广告客户或更低级别，并且必须已在 DoubleClick Search 中设置自定义指标。DoubleClick Search 中显示的自定义指标名称区分大小写。
`columns[].productReportPerspective`	`string`	仅返回特定类型的产品活动的指标。接受的值包括： “`sold`”：仅返回售出产品的指标 “`advertised`”：仅返回通过购物广告系列进行宣传并且不一定售出的产品的指标
`filters[].column.productReportPerspective`	`string`	仅返回特定类型的产品活动的指标。接受的值包括： “`sold`”：仅返回售出产品的指标 “`advertised`”：仅返回通过购物广告系列进行宣传并且不一定售出的产品的指标
`orderBy[].column.productReportPerspective`	`string`	仅返回特定类型的产品活动的指标。接受的值包括： “`sold`”：仅返回售出产品的指标 “`advertised`”：仅返回通过购物广告系列进行宣传并且不一定售出的产品的指标

响应

如果成功，此方法将在响应正文中返回一项 Reports 资源。

试试看！

请使用下面的 API Explorer 针对实际数据调用此方法并查看响应。或者，您也可以尝试独立广告 Explorer。