项目报表查询 API 文档
端点概述
按时间维度检索指定项目的统计报表数据（浏览量、转化数、收入），支持按天/周/月聚合，提供分页、状态筛选与字段排序能力，并支持基于 ETag 的缓存优化。适用于仪表盘展示与数据导出场景。
请求方法
- HTTP 方法与路径：GET /v1/projects/{projectId}/reports
- 鉴权方式：Bearer Token（OAuth2），在 Authorization 头中传入
- 媒体类型：Accept: application/json
请求参数
请求头
- Authorization: Bearer （必填）
用于 OAuth2 访问令牌。
- Accept: application/json（必填）
指定返回 JSON。
- If-None-Match: （可选）
客户端传入上次响应返回的 ETag 值以进行条件请求，命中时返回 304，减少带宽消耗。
路径参数
- projectId（string，必填）
项目唯一标识，例如：prj_7y2ab1。
查询参数
- type（string，可选，默认：daily）
报表类型：daily / weekly / monthly。
- start_date（string，必填）
起始日期，格式 YYYY-MM-DD。
- end_date（string，必填）
结束日期，格式 YYYY-MM-DD。
约束：日期区间最多 31 天。
- page（integer，可选，默认：1，范围：1–1000）
页码。
- page_size（integer，可选，默认：20，范围：1–100）
每页条数。
- sort（string，可选）
按字段排序，语法：<字段名>:<方向>，方向为 asc 或 desc。
示例：metrics.revenue:desc
支持的字段包含 metrics 下的统计字段：metrics.views、metrics.conversions、metrics.revenue。
- status（string，可选）
报表状态筛选：ready / pending。
响应格式
成功响应（200 OK）
响应头：
- Content-Type: application/json
- ETag: ""（用于后续 If-None-Match）
响应体示例结构：
- data（array
- meta（object）
- page（integer）当前页码
- page_size（integer）每页大小
- total_pages（integer）总页数
- total_items（integer）总条目数
- links（object）
- next（string，可选）下一页链接
- prev（string，可选）上一页链接
条件命中缓存（304 Not Modified）
当请求包含 If-None-Match 且与服务端资源 ETag 匹配时返回 304，无响应体。
错误响应
- 400 invalid_parameter
参数格式错误或日期区间不合法。
- 401 unauthorized
缺失或无效令牌。
- 404 project_not_found
项目不存在或无权限。
- 429 rate_limited
超过 60 次/分钟（项目级）限流。
说明：错误响应体格式未限定于此文档，如需解析错误详情，请根据返回的 HTTP 状态码与错误码处理。
使用示例
cURL：查询日维度报表（含分页）
curl -G 'https://api.example.io/v1/projects/prj_7y2ab1/reports' \
-H 'Authorization: Bearer <token>' \
-H 'Accept: application/json' \
--data-urlencode 'type=daily' \
--data-urlencode 'start_date=2024-03-01' \
--data-urlencode 'end_date=2024-03-07' \
--data-urlencode 'page=1' \
--data-urlencode 'page_size=20'
cURL：按收入倒序排序并使用缓存
curl -G 'https://api.example.io/v1/projects/prj_7y2ab1/reports' \
-H 'Authorization: Bearer <token>' \
-H 'Accept: application/json' \
-H 'If-None-Match: "W/\"abc123\""' \
--data-urlencode 'type=daily' \
--data-urlencode 'start_date=2024-03-01' \
--data-urlencode 'end_date=2024-03-07' \
--data-urlencode 'sort=metrics.revenue:desc'
示例响应（200 OK）
{
"data": [
{
"id": "rpt_20240301_d",
"type": "daily",
"period_start": "2024-03-01",
"period_end": "2024-03-01",
"metrics": { "views": 12045, "conversions": 342, "revenue": 15432.78 },
"generated_at": "2024-03-01T00:30:00Z",
"status": "ready"
}
],
"meta": { "page": 1, "page_size": 20, "total_pages": 3, "total_items": 52 },
"links": { "next": "/v1/projects/prj_7y2ab1/reports?page=2&type=daily" }
}
注意事项
- 鉴权：必须在 Authorization 请求头中携带有效的 Bearer Token，否则返回 401。
- 日期区间：start_date 与 end_date 为必填，日期格式必须为 YYYY-MM-DD，区间最多 31 天。
- 分页：page 取值范围 1–1000；page_size 取值范围 1–100。请结合 meta 与 links 进行翻页。
- 排序：支持字段级排序（例如 metrics.revenue:desc）。如未指定，使用默认排序（由服务端实现决定）。
- 状态：当仅有部分数据生成时，报表项的 status 可能为 pending；可通过 status 查询参数进行筛选。
- 缓存：服务端返回 ETag；客户端建议复用 ETag 并通过 If-None-Match 发起条件请求，命中返回 304 以减少带宽。
- 限流：项目级限流为 60 次/分钟，超过后返回 429 rate_limited；建议实现重试与退避策略。
- 错误处理：当参数非法（含日期区间不合法）返回 400 invalid_parameter；项目不存在或无权限返回 404 project_not_found。建议在客户端对参数进行预验证。
