126 lines
3.0 KiB
Markdown
126 lines
3.0 KiB
Markdown
# 数据分析活动接口说明
|
||
|
||
## 接口概述
|
||
`/api/activities` 端点提供了访问和导出分析事件数据的功能，可用于查询短链接的点击和访问记录。
|
||
|
||
## 请求方式
|
||
- HTTP 方法: **GET**
|
||
- URL: `/api/activities`
|
||
|
||
## 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|------|------|
|
||
| slug | string | 否* | 短链接标识符 |
|
||
| domain | string | 否* | 短链接域名 |
|
||
| format | string | 否 | 响应格式，可选值: `csv`（纯文本显示）；不传则默认返回JSON |
|
||
| startTime | string | 否* | 起始时间，ISO格式 |
|
||
| endTime | string | 否* | 结束时间，ISO格式 |
|
||
| page | number | 否 | 当前页码，默认为1 |
|
||
| pageSize | number | 否 | 每页记录数，默认为50 |
|
||
|
||
_*注：必须提供 (slug和domain) 或 (startTime和endTime) 中的至少一组过滤条件_
|
||
|
||
## 响应格式
|
||
|
||
### JSON格式（默认）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "事件ID",
|
||
"type": "事件类型",
|
||
"time": "事件时间",
|
||
"visitor": {
|
||
"id": "访问者ID",
|
||
"ipAddress": "IP地址",
|
||
"userAgent": "浏览器用户代理",
|
||
"referrer": "来源页面"
|
||
},
|
||
"device": {
|
||
"type": "设备类型",
|
||
"browser": "浏览器",
|
||
"os": "操作系统"
|
||
},
|
||
"location": {
|
||
"country": "国家",
|
||
"city": "城市"
|
||
},
|
||
"link": {
|
||
"id": "链接ID",
|
||
"slug": "短链标识",
|
||
"originalUrl": "原始链接",
|
||
"label": "链接标签",
|
||
"tags": ["标签1", "标签2"]
|
||
},
|
||
"utm": {
|
||
"source": "来源",
|
||
"medium": "媒介",
|
||
"campaign": "活动",
|
||
"term": "关键词",
|
||
"content": "内容"
|
||
}
|
||
}
|
||
],
|
||
"meta": {
|
||
"total": 总记录数,
|
||
"page": 当前页码,
|
||
"pageSize": 每页记录数
|
||
}
|
||
}
|
||
```
|
||
|
||
### CSV格式
|
||
|
||
当使用 `format=csv` 参数时，接口将返回以下列的CSV纯文本：
|
||
|
||
```
|
||
time,activity,campaign,clientId,originPath
|
||
2023-01-01 12:34:56,click,spring_sale,abc123,https://example.com/path?utm_campaign=spring_sale
|
||
```
|
||
|
||
列说明：
|
||
- `time`: 事件发生时间
|
||
- `activity`: 事件类型（如点击、访问等）
|
||
- `campaign`: 营销活动标识（从URL中的utm_campaign提取）
|
||
- `clientId`: 访问者标识的前半部分
|
||
- `originPath`: 原始请求路径或引荐URL
|
||
|
||
## 使用示例
|
||
|
||
### 基本查询（JSON）
|
||
```
|
||
GET /api/activities?slug=0326recap10&domain=example.com
|
||
```
|
||
|
||
### 导出CSV
|
||
```
|
||
GET /api/activities?slug=0326recap10&format=csv
|
||
```
|
||
|
||
### 按日期范围过滤
|
||
```
|
||
GET /api/activities?startTime=2023-03-01T00:00:00Z&endTime=2023-03-31T23:59:59Z
|
||
```
|
||
|
||
### 分页
|
||
```
|
||
GET /api/activities?slug=0326recap10&page=2&pageSize=100
|
||
```
|
||
|
||
## 错误响应
|
||
|
||
当请求参数不正确或服务器发生错误时，返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "错误描述信息"
|
||
}
|
||
```
|
||
|
||
常见错误代码：
|
||
- 400: 参数错误，例如缺少必要的过滤条件
|
||
- 500: 服务器内部错误 |