旧版 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` 参数是必需的。不能在同一个 stanza 中同时设置 `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 和 50000）。
`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 和 50000）。默认值为 `10000`。
`request.startRow`	`integer`	仅限同步报告。要返回的第一行的索引（从零开始）。可接受的值包括`0`到`50000`（含 0 和 50000）。默认值为 `0`。
`request.statisticsCurrency`	`string`	指定返回货币时使用的货币。`usdagencyadvertiseraccount`
`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 中均存在的所有子级实体（例如引擎账号、广告系列、广告组等）。
请求: 将报告请求插入报告系统。