372 lines
8.6 KiB
Markdown
372 lines
8.6 KiB
Markdown
# Discovery 模块 API 文档
|
||
|
||
本文档详细说明了 Discovery 模块的 API 接口，包括请求方法、URL、参数说明和响应格式。
|
||
|
||
## 目录
|
||
|
||
1. [通用说明](#通用说明)
|
||
2. [创作者搜索会话接口](#创作者搜索会话接口)
|
||
3. [创作者发现接口](#创作者发现接口)
|
||
|
||
## 通用说明
|
||
|
||
### 基础URL
|
||
|
||
所有 API 的基础 URL 为：`http://127.0.0.1:8000/api/discovery/`
|
||
|
||
### 认证方式
|
||
|
||
所有 API 都需要 Token 认证。请在请求头中添加：
|
||
|
||
```
|
||
Authorization: Token <your_token>
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
所有 API 返回的数据格式统一为：
|
||
|
||
```json
|
||
{
|
||
"code": 200, // 状态码，200表示成功，其他表示错误
|
||
"message": "成功", // 状态描述
|
||
"data": {} // 返回的数据，可能是对象、数组或null
|
||
}
|
||
```
|
||
|
||
### 分页
|
||
|
||
列表接口支持分页，默认每页 20 条数据，最大每页 100 条。
|
||
|
||
分页参数：
|
||
- `page`: 页码，从1开始
|
||
- `page_size`: 每页数量，默认20
|
||
|
||
分页响应格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"count": 100, // 总记录数
|
||
"next": "下一页URL", // 下一页链接，如果没有则为null
|
||
"previous": "上一页URL", // 上一页链接，如果没有则为null
|
||
"results": [] // 当前页数据
|
||
}
|
||
}
|
||
```
|
||
|
||
## 创作者搜索会话接口
|
||
|
||
搜索会话是指用户进行的一次创作者搜索，包含搜索结果和相关统计信息。
|
||
|
||
### 获取搜索会话列表
|
||
|
||
- **URL**: `/sessions/`
|
||
- **方法**: GET
|
||
- **描述**: 获取所有搜索会话的列表
|
||
- **参数**:
|
||
- 分页参数，参见[分页](#分页)部分
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取搜索会话列表成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"session_number": 123,
|
||
"creator_count": 100,
|
||
"shoppable_creators": 26,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2023-01-01"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 获取搜索会话详情
|
||
|
||
- **URL**: `/sessions/{session_id}/`
|
||
- **方法**: GET
|
||
- **描述**: 获取指定ID的搜索会话详细信息，包含搜索到的创作者列表
|
||
- **参数**:
|
||
- `session_id`: 会话ID (路径参数)
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取搜索会话详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 123,
|
||
"creator_count": 100,
|
||
"shoppable_creators": 26,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2023-01-01",
|
||
"creators": [
|
||
// 创作者列表，见创作者数据结构
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 创建搜索会话
|
||
|
||
- **URL**: `/sessions/`
|
||
- **方法**: POST
|
||
- **描述**: 创建新的搜索会话
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"session_number": 123,
|
||
"creator_count": 100,
|
||
"shoppable_creators": 26,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2023-01-01"
|
||
}
|
||
```
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "创建搜索会话成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 123,
|
||
"creator_count": 100,
|
||
"shoppable_creators": 26,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2023-01-01"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 更新搜索会话
|
||
|
||
- **URL**: `/sessions/{session_id}/`
|
||
- **方法**: PUT/PATCH
|
||
- **描述**: 更新搜索会话信息
|
||
- **参数**:
|
||
- `session_id`: 会话ID (路径参数)
|
||
- 请求体包含要更新的字段
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新搜索会话成功",
|
||
"data": {
|
||
// 更新后的会话信息
|
||
}
|
||
}
|
||
```
|
||
|
||
### 删除搜索会话
|
||
|
||
- **URL**: `/sessions/{session_id}/`
|
||
- **方法**: DELETE
|
||
- **描述**: 删除搜索会话
|
||
- **参数**:
|
||
- `session_id`: 会话ID (路径参数)
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除搜索会话成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 获取会话创作者列表
|
||
|
||
- **URL**: `/sessions/{session_id}/results/`
|
||
- **方法**: GET
|
||
- **描述**: 获取指定会话的搜索结果（创作者列表）
|
||
- **参数**:
|
||
- `session_id`: 会话ID (路径参数)
|
||
- 分页参数，参见[分页](#分页)部分
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取会话创作者列表成功",
|
||
"data": [
|
||
// 创作者列表，见创作者数据结构
|
||
]
|
||
}
|
||
```
|
||
|
||
## 创作者发现接口
|
||
|
||
### 获取创作者列表
|
||
|
||
- **URL**: `/creators/`
|
||
- **方法**: GET
|
||
- **描述**: 获取所有创作者的列表
|
||
- **参数**:
|
||
- 分页参数，参见[分页](#分页)部分
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取创作者列表成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "头像URL",
|
||
"category": "Phones & Electronics",
|
||
"ecommerce_level": "L2",
|
||
"exposure_level": "KOC-1",
|
||
"followers": 162.2,
|
||
"gmv": 534.1,
|
||
"items_sold": 18.1,
|
||
"avg_video_views": 1.9,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "抖音链接",
|
||
"session": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 获取创作者详情
|
||
|
||
- **URL**: `/creators/{creator_id}/`
|
||
- **方法**: GET
|
||
- **描述**: 获取指定ID的创作者详细信息
|
||
- **参数**:
|
||
- `creator_id`: 创作者ID (路径参数)
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取创作者详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "头像URL",
|
||
"category": "Phones & Electronics",
|
||
"ecommerce_level": "L2",
|
||
"exposure_level": "KOC-1",
|
||
"followers": 162.2,
|
||
"gmv": 534.1,
|
||
"items_sold": 18.1,
|
||
"avg_video_views": 1.9,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "抖音链接",
|
||
"session": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 搜索创作者
|
||
|
||
- **URL**: `/creators/search/`
|
||
- **方法**: POST
|
||
- **描述**: 根据条件搜索创作者并创建新的搜索会话
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"query": "搜索关键词",
|
||
"category": "Phones & Electronics", // 可选，见类别列表
|
||
"ecommerce_level": "L2", // 可选，见电商等级列表
|
||
"exposure_level": "KOC-1" // 可选，见曝光等级列表
|
||
}
|
||
```
|
||
- **响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索创作者成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 123,
|
||
"creator_count": 5,
|
||
"shoppable_creators": 3,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2023-01-01",
|
||
"creators": [
|
||
// 创作者列表，见创作者数据结构
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 数据结构
|
||
|
||
### 创作者类别
|
||
|
||
- `Phones & Electronics`: 手机与电子产品
|
||
- `Womenswear & Underwear`: 女装与内衣
|
||
- `Sports & Outdoor`: 运动与户外
|
||
- `Food & Beverage`: 食品与饮料
|
||
- `Health`: 健康
|
||
- `Kitchenware`: 厨具
|
||
- `Furniture`: 家具
|
||
- `Shoes`: 鞋类
|
||
- `Home Supplies`: 家居用品
|
||
|
||
### 电商等级
|
||
|
||
- `L1`: Level 1
|
||
- `L2`: Level 2
|
||
- `L3`: Level 3
|
||
- `L4`: Level 4
|
||
- `L5`: Level 5
|
||
- `New tag`: 新标签
|
||
|
||
### 曝光等级
|
||
|
||
- `KOC-1`: Key Opinion Consumer 1级
|
||
- `KOC-2`: Key Opinion Consumer 2级
|
||
- `KOL-2`: Key Opinion Leader 2级
|
||
- `KOL-3`: Key Opinion Leader 3级
|
||
- `New tag`: 新标签
|
||
|
||
### 创作者数据结构
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "头像URL",
|
||
"category": "Phones & Electronics",
|
||
"ecommerce_level": "L2",
|
||
"exposure_level": "KOC-1",
|
||
"followers": 162.2, // 单位：K (千)
|
||
"gmv": 534.1, // 单位：K (千)
|
||
"items_sold": 18.1, // 单位：K (千)
|
||
"avg_video_views": 1.9, // 单位：M (百万)
|
||
"has_ecommerce": true, // 是否有电商能力
|
||
"tiktok_url": "抖音链接",
|
||
"session": 1 // 所属搜索会话ID
|
||
}
|
||
```
|
||
|
||
### 搜索会话数据结构
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"session_number": 123, // 会话编号
|
||
"creator_count": 100, // 创作者数量
|
||
"shoppable_creators": 26, // 可购物创作者数量
|
||
"avg_followers": 162.2, // 平均粉丝数 (K)
|
||
"avg_gmv": 534.1, // 平均GMV (K)
|
||
"avg_video_views": 1.9, // 平均视频观看量 (M)
|
||
"date_created": "2023-01-01" // 创建日期
|
||
}
|
||
```
|