fix: remove downapp_id parameter from all APIs, use Bearer token auth
- All APIs now identify caller via Bearer Token, dapi module automatically provides user_id and org_id - rl_verify.dspy: use (await get_user()) instead of downapp_id param - rl_verify_user: rename downapp_id -> user_id param - rl_upload_user: rename downapp_id -> user_id param - rl_sync_asset_status_user: rename downapp_id -> user_id param - Update docs/api_downapp.md: remove all downapp_id references, add Bearer token auth description, add rl_query_groups and rl_callback documentation
This commit is contained in:
parent
af65c307f8
commit
dbf8473b1b
@ -1,12 +1,12 @@
|
||||
# Downapp API 接口文档
|
||||
# reallife_asset API 接口文档
|
||||
|
||||
## 概述
|
||||
本文档说明下游应用（Downapp）如何调用 `reallife_asset` 模块接口，完成真人人像素材的申请、认证、上传及状态查询。
|
||||
本文档说明下游应用如何调用 `reallife_asset` 模块接口，完成真人人像素材的认证、上传及状态查询。
|
||||
|
||||
**核心机制**：
|
||||
- 所有接口均通过 `downapp_id` 标识调用方。
|
||||
- 模块内部会自动检查调用方是否已开通服务（状态为 `active`）。
|
||||
- 密钥（AK/SK）由营运人员在后台维护，调用方无需在请求中传递。
|
||||
- 所有接口均通过 **Bearer Token** 认证，dapi 模块自动识别调用方身份，获取 `user_id` 和 `org_id`。
|
||||
- **调用方无需传递 `downapp_id`**，系统自动从认证上下文中获取用户和机构信息。
|
||||
- 供应商密钥（AK/SK）由营运人员在后台集中维护，调用方无需在请求中传递。
|
||||
|
||||
## 业务流程
|
||||
|
||||
@ -26,16 +26,17 @@
|
||||
### 请求参数
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `downapp_id` | 是 | 下游应用唯一标识 (用于追踪记录) |
|
||||
| `project_name` | 否 | 项目名称，默认 `default` |
|
||||
|
||||
> `user_id` 和 `org_id` 由 Bearer Token 自动获取，无需传递。
|
||||
|
||||
### 请求示例
|
||||
```http
|
||||
POST /reallife_asset/api/rl_verify.dspy
|
||||
Authorization: Bearer <your_api_key>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"downapp_id": "app_123",
|
||||
"project_name": "default"
|
||||
}
|
||||
```
|
||||
@ -70,19 +71,20 @@ Content-Type: application/json
|
||||
### 请求参数
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `downapp_id` | 是 | 下游应用唯一标识 |
|
||||
| `group_id` | 是 | 真人认证成功后获取的本地组合 ID |
|
||||
| `source_url` | 是 | 素材的公网可访问 URL |
|
||||
| `asset_type` | 否 | 素材类型：`Image` (默认) 或 `Video` |
|
||||
| `name` | 否 | 素材名称 |
|
||||
|
||||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||||
|
||||
### 请求示例
|
||||
```http
|
||||
POST /reallife_asset/api/rl_upload.dspy
|
||||
Authorization: Bearer <your_api_key>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"downapp_id": "app_123",
|
||||
"group_id": "local_group_id_xxx",
|
||||
"source_url": "https://bucket.oss.com/photo.jpg",
|
||||
"asset_type": "Image",
|
||||
@ -113,16 +115,17 @@ Content-Type: application/json
|
||||
### 请求参数
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `downapp_id` | 是 | 下游应用唯一标识 |
|
||||
| `asset_id` | 是 | 上传素材时返回的本地记录 ID |
|
||||
|
||||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||||
|
||||
### 请求示例
|
||||
```http
|
||||
POST /reallife_asset/api/rl_status.dspy
|
||||
Authorization: Bearer <your_api_key>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"downapp_id": "app_123",
|
||||
"asset_id": "asset_record_id_xxx"
|
||||
}
|
||||
```
|
||||
@ -139,11 +142,61 @@ Content-Type: application/json
|
||||
|
||||
---
|
||||
|
||||
## 4. 查询已认证的组合列表
|
||||
**Endpoint**: `/reallife_asset/api/rl_query_groups.dspy`
|
||||
|
||||
查询当前机构下所有已认证的组合 ID，用于上传素材时选择有效的 `group_id`。
|
||||
|
||||
### 请求参数
|
||||
无需参数，系统自动从 Bearer Token 获取 `org_id`。
|
||||
|
||||
### 请求示例
|
||||
```http
|
||||
POST /reallife_asset/api/rl_query_groups.dspy
|
||||
Authorization: Bearer <your_api_key>
|
||||
```
|
||||
|
||||
### 返回示例
|
||||
**成功**：
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"groups": [
|
||||
{
|
||||
"local_group_id": "local_group_id_xxx",
|
||||
"vendor_group_id": "vendor_group_xxx",
|
||||
"vendor": "volcengine",
|
||||
"status": "active",
|
||||
"create_time": "2026-05-28 15:30:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 认证回调（供应商调用）
|
||||
**Endpoint**: `/reallife_asset/api/rl_callback.dspy`
|
||||
|
||||
供应商 H5 认证完成后自动回调此接口，**调用方无需调用**。系统自动完成：
|
||||
- 查询认证结果
|
||||
- 登记 `rl_org_group` 映射关系
|
||||
- 更新 `rl_asset_group` 状态为 `active`
|
||||
|
||||
### 回调说明
|
||||
- 此接口为 **any** 权限（无需登录），供供应商 POST 回调使用
|
||||
- 回调 URL 在创建认证会话时由系统自动配置
|
||||
- 回调成功后，调用方可通过 `rl_query_groups` 查询到新的组合映射
|
||||
|
||||
---
|
||||
|
||||
## 错误代码说明
|
||||
|
||||
| 错误信息 | 原因 | 解决方案 |
|
||||
|----------|------|----------|
|
||||
| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 `rl_vendor_config` |
|
||||
| `供应商服务已停用` | 供应商配置状态非 active | 联系管理员激活配置 |
|
||||
| `无效的素材组合ID或无权访问` | `group_id` 不属于当前机构 | 确认是否已完成认证并使用正确的 ID |
|
||||
| `素材不存在或无权访问` | `asset_id` 无效或归属错误 | 检查 ID 是否正确 |
|
||||
| `参数缺失` | 缺少必填参数 | 检查请求 Body |
|
||||
| `未找到对应的认证会话` | `BytedToken` 无效 | 检查回调参数 |
|
||||
| `尚未完成认证或认证失败` | 认证未完成 | 等待用户完成 H5 认证 |
|
||||
|
||||
@ -409,7 +409,7 @@ async def _get_vendor_keys(vendor="volcengine"):
|
||||
return {"success": True, "ak": ak, "sk": sk, "callback_url": rec.callback_url}
|
||||
|
||||
|
||||
async def rl_verify_user(org_id, downapp_id, project_name="default"):
|
||||
async def rl_verify_user(org_id, user_id, project_name="default"):
|
||||
"""User proxy: Verify vendor config -> Call vendor -> Save org-group mapping."""
|
||||
keys = await _get_vendor_keys()
|
||||
if not keys.get("success"):
|
||||
@ -419,12 +419,6 @@ async def rl_verify_user(org_id, downapp_id, project_name="default"):
|
||||
client = _get_client("volcengine", keys["ak"], keys["sk"])
|
||||
callback_url = keys.get("callback_url", "")
|
||||
|
||||
# Note: downapp_id might be used to track who created it,
|
||||
# but the prompt focuses on org_id mapping.
|
||||
# We create a session for the user.
|
||||
# We need a unique callback URL if possible, or use the global one.
|
||||
# The global one usually has status in URL, but here we just use the global one.
|
||||
|
||||
result = client.create_visual_validate_session(callback_url, project_name)
|
||||
|
||||
if "error" in result:
|
||||
@ -434,16 +428,7 @@ async def rl_verify_user(org_id, downapp_id, project_name="default"):
|
||||
h5_link = result.get("H5Link", "")
|
||||
|
||||
# Save local record for checking status later
|
||||
# We save to rl_asset_group as before for internal tracking,
|
||||
# but link it to org via rl_org_group later?
|
||||
# Or just save to rl_asset_group with org_id.
|
||||
# The prompt says "登记用户机构可用的orgid...登记表".
|
||||
# Let's save to rl_asset_group first, then rl_org_group upon success.
|
||||
|
||||
# For simplicity, we return the H5 link.
|
||||
# We need to store the `byted_token` somewhere to check result later.
|
||||
# We'll use rl_asset_group for this temporary state.
|
||||
|
||||
# We use rl_asset_group for temporary state tracking
|
||||
gid = getID()
|
||||
now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
||||
db = DBPools()
|
||||
@ -452,7 +437,7 @@ async def rl_verify_user(org_id, downapp_id, project_name="default"):
|
||||
"id": gid,
|
||||
"org_id": org_id,
|
||||
"vendor": "volcengine",
|
||||
"name": f"待认证-{downapp_id}",
|
||||
"name": f"待认证-{user_id}",
|
||||
"title": f"待认证",
|
||||
"group_type": "LivenessFace",
|
||||
"project_name": project_name,
|
||||
@ -460,7 +445,7 @@ async def rl_verify_user(org_id, downapp_id, project_name="default"):
|
||||
"byted_token": byted_token,
|
||||
"h5_link": h5_link,
|
||||
"callback_url": callback_url,
|
||||
"created_by": downapp_id,
|
||||
"created_by": user_id or "",
|
||||
"create_time": now,
|
||||
"update_time": now,
|
||||
})
|
||||
@ -534,7 +519,7 @@ async def rl_check_validate_and_map(local_group_id, project_name="default"):
|
||||
return {"success": True, "vendor_group_id": vendor_group_id}
|
||||
|
||||
|
||||
async def rl_upload_user(org_id, group_id, source_url, asset_type, name, downapp_id):
|
||||
async def rl_upload_user(org_id, group_id, source_url, asset_type, name, user_id):
|
||||
"""User proxy: Validate Org-Group mapping -> Get Keys -> Upload."""
|
||||
# 1. Validate Group Ownership
|
||||
dbname = _get_dbname()
|
||||
@ -589,7 +574,7 @@ async def rl_upload_user(org_id, group_id, source_url, asset_type, name, downapp
|
||||
"asset_uri": asset_uri,
|
||||
"project_name": "default",
|
||||
"vendor_response": json.dumps(result, ensure_ascii=False),
|
||||
"created_by": downapp_id,
|
||||
"created_by": user_id or "",
|
||||
"create_time": now,
|
||||
"update_time": now,
|
||||
})
|
||||
@ -603,7 +588,7 @@ async def rl_upload_user(org_id, group_id, source_url, asset_type, name, downapp
|
||||
}
|
||||
|
||||
|
||||
async def rl_sync_asset_status_user(org_id, asset_id, downapp_id):
|
||||
async def rl_sync_asset_status_user(org_id, asset_id, user_id):
|
||||
"""User proxy: Validate ownership -> Get Keys -> Sync Status."""
|
||||
dbname = _get_dbname()
|
||||
db = DBPools()
|
||||
|
||||
@ -1,8 +1,4 @@
|
||||
downapp_id = params_kw.get('downapp_id', '')
|
||||
project_name = params_kw.get('project_name', 'default')
|
||||
|
||||
if not downapp_id:
|
||||
return {"success": False, "message": "downapp_id 不能为空"}
|
||||
|
||||
result = await rl_verify_user((await get_userorgid()) or '0', downapp_id, project_name)
|
||||
result = await rl_verify_user((await get_userorgid()) or '0', (await get_user()) or '', project_name)
|
||||
return result
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user