329 lines
7.9 KiB
Markdown
329 lines
7.9 KiB
Markdown
# Discovery API 接口文档
|
||
|
||
## 简介
|
||
|
||
Discovery API是一个用于发现和搜索创作者的接口。它提供了创作者搜索、搜索会话管理等功能。所有API响应均遵循统一格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200, // 状态码，200表示成功
|
||
"message": "操作成功", // 操作提示消息
|
||
"data": { // 实际数据
|
||
// 具体内容
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用Apifox测试接口
|
||
|
||
1. 下载并安装Apifox: https://www.apifox.cn/
|
||
2. 创建新项目，命名为"Creator Discovery"
|
||
3. 导入API或手动创建以下接口
|
||
|
||
## API 接口列表
|
||
|
||
### 1. 搜索创作者
|
||
|
||
- **URL**: `http://localhost:8000/api/discovery/creators/search/`
|
||
- **方法**: POST
|
||
- **描述**: 根据条件搜索创作者，并创建新的搜索会话
|
||
- **请求参数**:
|
||
|
||
```json
|
||
{
|
||
"query": "创作者",
|
||
"category": "Health",
|
||
"ecommerce_level": "L5",
|
||
"exposure_level": "KOL-2"
|
||
}
|
||
```
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索创作者成功",
|
||
"data": {
|
||
"id": 4,
|
||
"creators": [
|
||
{
|
||
"id": 37,
|
||
"name": "Mock Creator 5",
|
||
"avatar": null,
|
||
"category": "Health",
|
||
"ecommerce_level": "L5",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 162.2,
|
||
"gmv": 534.1,
|
||
"items_sold": 18.1,
|
||
"avg_video_views": 1.9,
|
||
"has_ecommerce": false,
|
||
"tiktok_url": null,
|
||
"session": 4
|
||
}
|
||
],
|
||
"session_number": 4,
|
||
"creator_count": 1,
|
||
"shoppable_creators": 0,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2023-10-02"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取搜索会话列表
|
||
|
||
- **URL**: `http://localhost:8000/api/discovery/sessions/`
|
||
- **方法**: GET
|
||
- **描述**: 获取所有搜索会话的历史记录
|
||
- **查询参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页条数，默认为20，最大为100
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"count": 3,
|
||
"next": "http://localhost:8000/api/discovery/sessions/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 42,
|
||
"shoppable_creators": 24,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2024-01-06"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"session_number": 2,
|
||
"creator_count": 53,
|
||
"shoppable_creators": 13,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2022-01-07"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 获取搜索会话详情
|
||
|
||
- **URL**: `http://localhost:8000/api/discovery/sessions/{id}/`
|
||
- **方法**: GET
|
||
- **描述**: 获取特定搜索会话的详细信息，包含该会话中的所有创作者
|
||
- **请求参数**: 路径参数 `id`
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取搜索会话详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"creators": [
|
||
{
|
||
"id": 1,
|
||
"name": "Creator 1 in Session 1",
|
||
"avatar": null,
|
||
"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": null,
|
||
"session": 1
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "Creator 9 in Session 1",
|
||
"avatar": null,
|
||
"category": "Womenswear & Underwear",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-3",
|
||
"followers": 162.2,
|
||
"gmv": 534.1,
|
||
"items_sold": 18.1,
|
||
"avg_video_views": 1.9,
|
||
"has_ecommerce": false,
|
||
"tiktok_url": null,
|
||
"session": 1
|
||
}
|
||
],
|
||
"session_number": 1,
|
||
"creator_count": 42,
|
||
"shoppable_creators": 24,
|
||
"avg_followers": 162.2,
|
||
"avg_gmv": 534.1,
|
||
"avg_video_views": 1.9,
|
||
"date_created": "2024-01-06"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 获取会话中的创作者
|
||
|
||
- **URL**: `http://localhost:8000/api/discovery/sessions/{id}/results/`
|
||
- **方法**: GET
|
||
- **描述**: 获取特定会话中的所有创作者
|
||
- **请求参数**:
|
||
- 路径参数 `id`
|
||
- 查询参数 `page`、`page_size`（分页参数）
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"count": 42,
|
||
"next": "http://localhost:8000/api/discovery/sessions/1/results/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"name": "Creator 1 in Session 1",
|
||
"avatar": null,
|
||
"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": null,
|
||
"session": 1
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "Creator 9 in Session 1",
|
||
"avatar": null,
|
||
"category": "Womenswear & Underwear",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-3",
|
||
"followers": 162.2,
|
||
"gmv": 534.1,
|
||
"items_sold": 18.1,
|
||
"avg_video_views": 1.9,
|
||
"has_ecommerce": false,
|
||
"tiktok_url": null,
|
||
"session": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 获取所有创作者
|
||
|
||
- **URL**: `http://localhost:8000/api/discovery/creators/`
|
||
- **方法**: GET
|
||
- **描述**: 获取系统中的所有创作者
|
||
- **请求参数**: 查询参数 `page`、`page_size`（分页参数）
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"count": 150,
|
||
"next": "http://localhost:8000/api/discovery/creators/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"name": "Creator 1 in Session 1",
|
||
"avatar": null,
|
||
"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": null,
|
||
"session": 1
|
||
},
|
||
// 更多创作者...
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 获取创作者详情
|
||
|
||
- **URL**: `http://localhost:8000/api/discovery/creators/{id}/`
|
||
- **方法**: GET
|
||
- **描述**: 获取特定创作者的详细信息
|
||
- **请求参数**: 路径参数 `id`
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取创作者详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "Creator 1 in Session 1",
|
||
"avatar": null,
|
||
"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": null,
|
||
"session": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## 在Apifox中设置环境变量
|
||
|
||
创建一个名为"本地开发环境"的环境，设置以下变量：
|
||
- `baseUrl`: `http://localhost:8000/api`
|
||
|
||
这样可以在所有请求中使用`{{baseUrl}}/discovery/...`来替代完整URL。
|
||
|
||
## 测试流程示例
|
||
|
||
1. 启动Django服务器：`python manage.py runserver`
|
||
2. 在Apifox中发送请求"获取搜索会话列表"
|
||
3. 在响应中选择一个会话ID
|
||
4. 使用该ID获取会话详情
|
||
5. 使用"搜索创作者"接口创建新的搜索会话
|
||
6. 验证新创建的会话是否出现在会话列表中
|
||
|
||
## 在Apifox中导入API
|
||
|
||
1. 在Apifox中，点击"导入"按钮
|
||
2. 选择"导入API"
|
||
3. 将本文档中的API信息整理成集合导入
|
||
4. 设置每个接口的请求和响应格式
|
||
5. 设置示例响应
|
||
|
||
## 注意事项
|
||
|
||
- 所有API响应均遵循统一的格式：`code`、`message`和`data`
|
||
- 分页接口返回格式为：`{ "code": 200, "message": "获取数据成功", "data": { "count": 总数, "next": 下一页URL, "previous": 上一页URL, "results": [] } }`
|
||
- 即使发生错误，HTTP状态码始终为200，错误信息在响应体的`code`和`message`中提供
|
||
- 接口不需要认证，可直接访问 |