shorturl-analytics/app/api/activities/readme.md

数据分析活动接口说明

接口概述

/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格式（默认）

{
  "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

错误响应

当请求参数不正确或服务器发生错误时，返回以下格式：

{
  "success": false,
  "error": "错误描述信息"
}

常见错误代码：

• 400: 参数错误，例如缺少必要的过滤条件
• 500: 服务器内部错误