旧版 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

如需了解此资源的方法列表，请参阅本页结尾部分。

资源表示形式

DoubleClick Search 报表。此对象包含报告请求、某些报告元数据（如货币代码）以及生成的报告行或报告文件。

{
  "kind": "doubleclicksearch#report",
  "id": string,
  "isReportReady": boolean,
  "request": {
    "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
  },
  "statisticsCurrencyCode": string,
  "statisticsTimeZone": string,
  "rowCount": integer,
  "files": [
    {
      "url": string,
      "byteCount": long
    }
  ],
  "rows": [
    {
      (key): (value)
    }
  ]
}

属性名称	值	说明
`files[]`	`list`	仅异步报告。包含报告成功完成后生成的报告文件的列表。
`files[].byteCount`	`long`	此报表文件的大小（以字节为单位）。
`files[].url`	`string`	使用此网址下载报告文件。
`id`	`string`	仅异步报告。报告的 ID。
`isReportReady`	`boolean`	仅异步报告。当且仅当报告已成功完成且报告文件可供下载时，值为 true。
`kind`	`string`	将其标识为报告资源。值：固定字符串 `doubleclicksearch#report`。
`request`	`nested object`	创建报告的请求。原始请求中未指定的可选字段会填充默认值。
`request.columns[]`	`list`	要包含在报告中的列。这包括 DoubleClick Search 列和已保存的列。对于 DoubleClick Search 列，只有 `columnName` 参数是必需的。对于已保存的列，只有 `savedColumnName` 参数是必需的。不能在同一节中设置 `columnName` 和 `savedColumnName`。每个请求的列数上限为 300。
`request.columns[].columnName`	`string`	要添加到报表中的 DoubleClick Search 列的名称。
`request.columns[].customDimensionName`	`string`	按自定义维度细分报告。此报表的范围仅限于广告客户或更低级别，并且 DoubleClick Search 中必须已经设置了自定义维度。DoubleClick Search 中显示的自定义维度名称区分大小写。在转化报告中使用时，返回指定转化的指定自定义维度的值（如果已设置）。此列不会细分转化报告。
`request.columns[].customMetricName`	`string`	要包含在报告中的自定义指标的名称。报表必须已定位到广告客户或更小的范围，并且已在 DoubleClick Search 中设置了自定义指标。DoubleClick Search 中显示的自定义指标名称区分大小写。
`request.columns[].endDate`	`string`	包含 YYYY-MM-DD 格式的当天。如果提供，则此数据将仅替换此列所在报表的总体时间范围。必须与 `startDate` 一起提供。
`request.columns[].groupByColumn`	`boolean`	仅限同步报表。设置为 `true` 可按此列分组。默认值为 `false`。
`request.columns[].headerText`	`string`	用于标识报告输出中此列的文本；如果未指定，则默认为 `columnName` 或 `savedColumnName`。这可用于防止 DoubleClick Search 列与同名的已保存列之间发生冲突。
`request.columns[].platformSource`	`string`	用于提供自定义维度数据的平台。可接受的值为“Floodlight”。
`request.columns[].productReportPerspective`	`string`	仅返回特定类型商品活动的指标。接受的值包括： “`sold`”：仅返回所售产品的指标 “`advertised`”：仅返回在购物广告系列中所宣传的产品（无论是否已售出）的指标
`request.columns[].savedColumnName`	`string`	要包含在报告中的已保存列的名称。报表的范围必须在广告客户或更小范围内，并且此已保存的列必须已在 DoubleClick Search 界面中创建。
`request.columns[].startDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。如果提供，则此数据将仅替换此列所在报表的总体时间范围。必须与 `endDate` 一起提供。
`request.downloadFormat`	`string`	报告应采用的格式。目前支持 `csv` 或 `tsv`。
`request.filters[]`	`list`	应用到报告的一系列过滤器。每个请求的过滤器数量上限为 300 个。
`request.filters[].column`	`nested object`	要对其执行过滤的列。这一列可以是 DoubleClick Search 列，也可以是已保存的列。
`request.filters[].column.columnName`	`string`	要添加到报表中的 DoubleClick Search 列的名称。
`request.filters[].column.customDimensionName`	`string`	按自定义维度细分报告。此报表的范围仅限于广告客户或更低级别，并且 DoubleClick Search 中必须已经设置了自定义维度。DoubleClick Search 中显示的自定义维度名称区分大小写。在转化报告中使用时，返回指定转化的指定自定义维度的值（如果已设置）。此列不会细分转化报告。
`request.filters[].column.customMetricName`	`string`	要包含在报告中的自定义指标的名称。报表必须已定位到广告客户或更小的范围，并且已在 DoubleClick Search 中设置了自定义指标。DoubleClick Search 中显示的自定义指标名称区分大小写。
`request.filters[].column.endDate`	`string`	包含 YYYY-MM-DD 格式的当天。如果提供，则此数据将仅替换此列所在报表的总体时间范围。必须与 `startDate` 一起提供。
`request.filters[].column.groupByColumn`	`boolean`	仅限同步报表。设置为 `true` 可按此列分组。默认值为 `false`。
`request.filters[].column.headerText`	`string`	用于标识报告输出中此列的文本；如果未指定，则默认为 `columnName` 或 `savedColumnName`。这可用于防止 DoubleClick Search 列与同名的已保存列之间发生冲突。
`request.filters[].column.platformSource`	`string`	用于提供自定义维度数据的平台。可接受的值为“Floodlight”。
`request.filters[].column.productReportPerspective`	`string`	仅返回特定类型商品活动的指标。接受的值包括： “`sold`”：仅返回所售产品的指标 “`advertised`”：仅返回在购物广告系列中所宣传的产品（无论是否已售出）的指标
`request.filters[].column.savedColumnName`	`string`	要包含在报告中的已保存列的名称。报表的范围必须在广告客户或更小范围内，并且此已保存的列必须已在 DoubleClick Search 界面中创建。
`request.filters[].column.startDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。如果提供，则此数据将仅替换此列所在报表的总体时间范围。必须与 `endDate` 一起提供。
`request.filters[].operator`	`string`	要在过滤器中使用的运算符。如需查看可用运算符的列表，请参阅过滤条件参考文档。
`request.filters[].values[]`	`list`	用于过滤列值的值的列表。每个请求的过滤条件值数量上限为 300 个。
`request.includeDeletedEntities`	`boolean`	确定是否应在报告中包含已移除的实体。默认为 `false`。已弃用，请改用 `includeRemovedEntities`。
`request.includeRemovedEntities`	`boolean`	确定是否应在报告中包含已移除的实体。默认为 `false`。
`request.maxRowsPerFile`	`integer`	仅异步报告。每个报表文件的行数上限。系统会将一个大型报表拆分成多个文件（基于此字段）。可接受的值包括`1000000`到`100000000`（含 0 和 5000）。
`request.orderBy[]`	`list`	仅限同步报表。定义要对报告行进行排序的列和方向列表。每个请求的最大订单数为 300。
`request.orderBy[].column`	`nested object`	要对其排序的列。这一列可以是 DoubleClick Search 定义的列，也可以是已保存的列。
`request.orderBy[].column.columnName`	`string`	要添加到报表中的 DoubleClick Search 列的名称。
`request.orderBy[].column.customDimensionName`	`string`	按自定义维度细分报告。此报表的范围仅限于广告客户或更低级别，并且 DoubleClick Search 中必须已经设置了自定义维度。DoubleClick Search 中显示的自定义维度名称区分大小写。在转化报告中使用时，返回指定转化的指定自定义维度的值（如果已设置）。此列不会细分转化报告。
`request.orderBy[].column.customMetricName`	`string`	要包含在报告中的自定义指标的名称。报表必须已定位到广告客户或更小的范围，并且已在 DoubleClick Search 中设置了自定义指标。DoubleClick Search 中显示的自定义指标名称区分大小写。
`request.orderBy[].column.endDate`	`string`	包含 YYYY-MM-DD 格式的当天。如果提供，则此数据将仅替换此列所在报表的总体时间范围。必须与 `startDate` 一起提供。
`request.orderBy[].column.groupByColumn`	`boolean`	仅限同步报表。设置为 `true` 可按此列分组。默认值为 `false`。
`request.orderBy[].column.headerText`	`string`	用于标识报告输出中此列的文本；如果未指定，则默认为 `columnName` 或 `savedColumnName`。这可用于防止 DoubleClick Search 列与同名的已保存列之间发生冲突。
`request.orderBy[].column.platformSource`	`string`	用于提供自定义维度数据的平台。可接受的值为“Floodlight”。
`request.orderBy[].column.productReportPerspective`	`string`	仅返回特定类型商品活动的指标。接受的值包括： “`sold`”：仅返回所售产品的指标 “`advertised`”：仅返回在购物广告系列中所宣传的产品（无论是否已售出）的指标
`request.orderBy[].column.savedColumnName`	`string`	要包含在报告中的已保存列的名称。报表的范围必须在广告客户或更小范围内，并且此已保存的列必须已在 DoubleClick Search 界面中创建。
`request.orderBy[].column.startDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。如果提供，则此数据将仅替换此列所在报表的总体时间范围。必须与 `endDate` 一起提供。
`request.orderBy[].sortOrder`	`string`	排序方向，可以是 `ascending` 或 `descending`。
`request.reportScope`	`object`	reportScope 是一组 ID，用于确定报告中要返回的实体子集。需要通过代理机构所需范围最小的级别的完整 ID 沿袭。
`request.reportScope.adGroupId`	`long`	DS 广告组 ID。
`request.reportScope.adId`	`long`	DS 广告 ID。
`request.reportScope.advertiserId`	`long`	DS 广告客户 ID。
`request.reportScope.agencyId`	`long`	DS 代理机构 ID。
`request.reportScope.campaignId`	`long`	DS 广告系列 ID。
`request.reportScope.engineAccountId`	`long`	DS 引擎帐号 ID。
`request.reportScope.keywordId`	`long`	DS 关键字 ID。
`request.reportType`	`string`	确定报表中所返回行的类型。例如，如果您指定 `reportType: keyword`，则报表中的每一行将包含关键字的相关数据。有关每种类型可用的列，请参阅报告类型参考。
`request.rowCount`	`integer`	仅限同步报表。要返回的行数上限；额外的行会被丢弃。可接受的值包括`0`到`10000`（含 0 和 5000）。默认值为 `10000`。
`request.startRow`	`integer`	仅限同步报表。要返回的第一行的索引（从零开始）。可接受的值包括`0`到`50000`（含 0 和 5000）。默认值为 `0`。
`request.statisticsCurrency`	`string`	指定以何种货币返回货币。可能的值包括：`usd`、`agency`（如果报表的范围限定为代理机构或更低级别，则有效）、`advertiser`（如果报表的范围限定为 * 广告客户或更低级别则有效）或 `account`（如果报表的范围限定在引擎帐号或更低级别，则有效）。
`request.timeRange`	`object`	如果报告请求指标，此参数将用于限制特定时间范围内的指标。
`request.timeRange.changedAttributesSinceTimestamp`	`datetime`	包含 RFC 格式的 UTC 时间戳，例如`2013-07-16T10:16:23.555Z`。请参阅其他参考资料，了解更改后的属性报告的运作方式。
`request.timeRange.changedMetricsSinceTimestamp`	`datetime`	包含 RFC 格式的 UTC 时间戳，例如`2013-07-16T10:16:23.555Z`。如需更多参考，了解“更改的指标”报告的运作方式。
`request.timeRange.endDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。
`request.timeRange.startDate`	`string`	包含日期，采用 YYYY-MM-DD 格式。
`request.verifySingleTimeZone`	`boolean`	如果为 `true`，则仅当所请求的全部统计数据都来自单个时区时，系统才会创建此报告。默认值为 `false`。
`rowCount`	`integer`	报告生成的报告行数（不包括标题）。
`rows[]`	`list`	仅限同步报表。生成的报告行。
`rows[].(key)`	`any value`	指示此行中表示的列。也就是说，每个键都对应一行中含有非空单元格的列。
`statisticsCurrencyCode`	`string`	报告中生成的所有货币价值的货币代码，包括用户设置的值（如关键字出价设置）和指标（如费用和收入）。报告的货币代码由报告请求的 `statisticsCurrency` 字段决定。
`statisticsTimeZone`	`string`	如果报表的所有统计数据都来自相同的时区，则报表就是这个时区。否则，该字段将处于未设置状态。

方法

生成: 立即生成报表并返回。
get: 针对报告请求的状态进行投票。
getFile: 下载使用 UTF-8 编码的报告文件。
getIdMappingFile: 下载一个 CSV 文件（采用 UTF-8 编码），其中包含旧版 Search Ads 360 和新版 Search Ads 360 之间的 ID 映射。对于请求的广告客户，该文件会同时包含旧版 Search Ads 360 和新版 Search Ads 360 中的所有子实体（例如引擎帐号、广告系列、广告组等）。
请求: 将报告请求插入报告系统。