如需了解此资源的方法列表,请参阅本页结尾部分。
资源表示形式
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 |
仅返回特定类型商品活动的指标。接受的值包括:
|
|
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 |
仅返回特定类型商品活动的指标。接受的值包括:
|
|
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 |
仅返回特定类型商品活动的指标。接受的值包括:
|
|
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 中的所有子实体(例如引擎帐号、广告系列、广告组等)。
- 请求
- 将报告请求插入报告系统。