API参考 | 报表服务
报表服务 (ReportService)
通过 ReportService ，您可以获取推广效果的详细报表。由于产生报表需要一定的时间，我们采用了异步的方式对报表进行处理。您首先需要通过 getReportId() 方法获得一个字符串类型的 reportId ，然后通过 pull 的方式轮询调用 getReportState() 方法检查报表是否产生。待产生后，则可调用 getReportPath() 方法获取报表的下载地址。根据该地址即可下载您所需要的报表。
报告 id 采用 <32 位 16 进制数 > 的取值形式，例如： 8e7e3f2d84a19c5df1415957434b2bd8
数据类型
接口描述
getReportId
方法说明：求绩效数据报告
输入信息： getReportIdRequest ：绩效数据的查询条件，只有一个 ReportRequestType 对象 ，该对象说明如下 :
| 属性名 |
类型 |
说明 |
限制 |
| performanceData |
String[] |
指定绩效数据 |
必填
取值范围： cost cpc click position
cost： 消耗
consumePercent： 消耗占比
cpc： 点击均价
click： 点击数
clickPercent： 点击占比
position： 关键词平均排名
|
| startDate |
dateTime |
统计开始时间，格式参考：
2010-08-01T00:00:00.000 |
必填 |
| endDate |
dateTime |
统计结束时间，格式参考：
2010-08-17T23:59:59.000 |
必填 |
| idOnly |
Boolean |
是否只需要 id |
选填；默认为 false
取值范围：
true ：只获取 id
false ：既获取 id 也获取字面 |
| levelOfDetails |
Integer |
统计粒度 |
选填；默认值为1；
下列取值范围仅用于地域报告：
1：账户范围
2：计划范围 |
| Opt |
Opt |
针对特定的报告类型设置特定的统计范围 |
无效属性 |
| format |
Integer |
报告文件格式 |
选填，默认值为 1 ；
1 ： csv 格式(gzip压缩) |
| reportType |
Integer |
报告类型 |
必填；
说明：分钟级报告需要开发
1 ：账户报告（支持分时及分钟级报告）
2 ：计划报告（支持分时及分钟级报告）
3 ：推广组报告 （支持分时及分钟级报告）
4 ：创意报告
5 ：关键词报告 (cpcid) 报告（支持分时及分钟级报告）
6 ：搜索词报告
13 ：地域报告
14 ：二级地域报告
|
| statRange |
Integer |
统计范围 |
选填，默认值为 1 ；
1 ：账户范围
2 ：计划范围
3 ：推广组范围
4 ：创意范围
5 ：关键词 (cpcid) 范围
注意：统计范围不能细于当前的统计粒度，例如统计粒度为计划，则统计范围不能细到推广组
|
| statIds |
Long[] |
统计范围下的 id 集合。根据 StatRange 的不同类型填写不同 id |
选填，默认 NULL ，表示统计范围为全账户
statRange 为 2 时填写计划 id;
statRange 为 3 时填写推广组 id;
statRange 为 4 时填写创意 id;
statRange 为 5 时填写关键词 调取指定分钟级关键词时,数组内关键词个数为200;
statRange 为 6 时填写附加样式id; |
| unitOfTime |
Integer |
统计时间单位 |
选填，默认值为 1
取值范围：
1 ：日报
2 ：周报
3 ：月报 （搜索词报告不支持月报）
4 ：分时报告（仅支持账户报告、推广计划报告、推广组报告、关键词报告）
5：分钟级报告（仅支持当天的账户报告、推广计划报告、推广组报告、关键词报告） |
| regions |
Integer[] |
投放地区列表 |
选填，默认为0
取值范围：
（选填）默认全部区域,取值范围参考地域代码;
地域代码个数上限15;
该字段仅针对于指定关键词报告;
|
| showLocateMode |
Integer |
展现定位方式 |
选填，默认为0
取值范围：
0：否
1：是
仅用于地域数据报告;
|
返回信息： getReportIdResponse ：含有本次请求所返回的 reportId.
| 属性名 |
类型 |
说明 |
限制 |
| reportId |
String |
生成的报告 ID |
ID 为一串 MD5 值，格式为 32 位 16 进制数标示，例如 8e7e3f2d84a19c5df1415957434b2bd8 |
getReportState
方法说明：查询报告是否生成
输入信息： getReportStateRequest
| 属性名 |
类型 |
说明 |
限制 |
| reportId |
String |
请求的报告 ID |
|
返回信息： getReportStateResponse：
| 属性名 |
类型 |
说明 |
限制 |
| isGenerated |
Integer |
报告生成状态 |
1: 已完成
0: 处理中
-1:报表生成异常 |
附加说明：在获取 Report 下载 url 前，请调用此方法。待确认报表已生成时，再获取下载的 url 。
getReportPath
方法说明：获取报告下载地址
输入信息： getReportPathRequest
| 属性名 |
类型 |
说明 |
限制 |
| reportId |
String |
报告 ID |
|
返回信息： getReportPathResponse
| 属性名 |
类型 |
说明 |
限制 |
| reportFilePath |
String |
下载地址 |
|
报表限制
报告格式：
报告采用CSV格式，分隔符为逗号
数据容量：
建议返回的文件不要超过 10 万条数据
时间跨度：
报告时间跨度不得超过1年
搜索词历史报告最多只提供最近92天的数据，搜索词实时报告可以获取今天的累计数据（不包含一小时内的数据，且不可跨天取）
关键词报告可提供近一年的数据，但其中的关键词平均排名这一列最多只提供最近30天的数据
关键词报告（含有展现无点击数据）可提供近三个月的数据，时间跨度不得超过30天
分时报告最多只提供最近92天的数据,统计时间跨度不超过31天
在请求报表时，请注意控制参数值，尤其是起止时间参数。如果您账户数据比较多，起止时间又过大，可能会导致报表无法正确生成。如果在正确获得报表 id 后，超过 5 分钟无法获得报表，说明您的参数的设置不合适
分钟级报告限制：
分钟级报告只支持查询当天的数据，时间跨度不得超过半个小时，有一个小时的延迟，除此之外还有一个总体限制条件：
statIds个数*platform类别* regions区域个数*时间段<=500000
公式解释：
Platform选择0时，则计算时platform类别取值为2;
时间段是指起始时间到结束时间之间的分钟个数;
Regions该字段仅针对于指定关键词数据报告时使用，若不填，则默认全部地域地域;
数据实时性：
当天九点之后可以获取昨天的数据
报告数量：
您的报告请求数量不受限制
报告有效期：
1 周