Files
aibridge/docs/interface-oauth/02-usage-guide.md
T
2026-05-18 09:28:15 +08:00

177 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 使用指南
## 完整示例
### 场景:创建第三方应用访问权限
假设你需要为第三方合作方创建一个只能访问"当前用户"和"行政区划"两个接口的应用。
### 1. 准备工作
```python
from aibridge import JNPFClient, JNPFConfig
client = JNPFClient.from_config(JNPFConfig())
client.login()
oauth = client.interface_oauth
di = client.data_interface
# 先验证要授权的接口存在
di_id_1 = "83ae1f5e5c26447b8c4849ead352b048" # 当前用户
di_id_2 = "420587863533428357" # 行政区划
```
### 2. 创建认证
```python
# 获取新秘钥
secret_resp = oauth.get_app_secret()
app_secret = secret_resp.data
print(f"生成的秘钥: {app_secret}")
# 创建认证
resp = oauth.create({
"appId": "partner_app", # 唯一应用ID
"appName": "合作伙伴应用", # 应用名称
"appSecret": app_secret, # 秘钥
"verifySignature": 0, # 不启用签名验证
"enabledMark": 1, # 启用
"whiteList": "192.168.1.1,10.0.0.0/8", # IP白名单
})
print(f"创建结果: {resp.msg}")
```
### 3. 绑定授权接口
```python
# 绑定授权接口
resp = oauth.bind_interfaces(resp.data, [di_id_1, di_id_2])
print(f"绑定结果: {resp.msg}")
# 查看详情确认
info = oauth.get_info(resp.data)
print(f"授权接口数: {len(info.data.get('list', []))}")
```
### 4. 授权用户(可选)
如果需要记录调用方用户:
```python
# 获取用户信息
user_resp = oauth.save_user_list(resp.data, [
{"userId": "user_id_123", "userKey": "partner_user_1"},
])
```
### 5. 外部系统调用
```python
import requests
app_id = "partner_app"
app_secret = "之前生成的秘钥"
di_id = di_id_1 # 当前用户接口
# 调用 GET 接口
response = requests.get(
f"http://localhost:30000/api/system/DataInterface/{di_id}/Actions/Response",
headers={
"Authorization": f"{app_id}::{app_secret}",
"UserKey": "partner_user_1",
}
)
print(response.json())
```
## 高级配置
### 启用签名验证
```python
# 创建时启用签名
resp = oauth.create({
"appId": "secure_app",
"appName": "安全应用",
"appSecret": app_secret,
"verifySignature": 1, # 启用签名验证
"enabledMark": 1,
})
```
### 设置使用期限
```python
from datetime import datetime, timedelta
# 设置30天后过期
expire_date = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")
resp = oauth.create({
"appId": "temp_app",
"appName": "临时应用",
"appSecret": app_secret,
"usefulLife": expire_date,
"enabledMark": 1,
})
```
### 管理授权接口
```python
# 查看当前授权
info = oauth.get_info(oauth_id)
current_ids = [item['id'] for item in info.data.get('list', [])]
# 添加一个新接口
new_ids = current_ids + ["new_di_id"]
oauth.bind_interfaces(oauth_id, new_ids)
# 移除一个接口
oauth.bind_interfaces(oauth_id, [di_id_1]) # 只保留一个
```
## 常见问题
### Q: 如何限制第三方只能访问特定接口?
```python
# 绑定时只指定允许的接口
oauth.bind_interfaces(oauth_id, ["di_id_1", "di_id_2"])
```
### Q: 如何吊销一个应用的访问权限?
```python
# 方式1:禁用
oauth.update({"id": oauth_id, "enabledMark": 0})
# 方式2:删除
oauth.delete(oauth_id)
```
### Q: 如何查看接口调用情况?
```python
# 获取调用日志
logs = oauth.get_log(oauth_id, {"currentPage": 1, "pageSize": 20})
for log in logs.data.get('list', []):
print(f"时间: {log.get('creatorTime')}, IP: {log.get('ipAddress')}, 接口: {log.get('fullName')}")
```
### Q: 签名验证失败怎么办?
1. 确认 `verifySignature` 设置正确(0 或 1)
2. 如果启用签名,确认时间戳在1分钟内
3. 确认 appSecret 正确(注意是否有前后空格)
4. 参考 `01-auth-mechanism.md` 检查签名算法
## 安全建议
1. **启用签名验证**:生产环境建议 `verifySignature=1`
2. **设置 IP 白名单**:限制只有已知 IP 可以访问
3. **设置使用期限**:临时应用设置过期时间
4. **最小授权**:只授权必要的接口
5. **定期轮换秘钥**:定期调用 `get_app_secret` 更新秘钥