177 lines
4.1 KiB
Markdown
177 lines
4.1 KiB
Markdown
# 使用指南
|
||
|
||
## 完整示例
|
||
|
||
### 场景:创建第三方应用访问权限
|
||
|
||
假设你需要为第三方合作方创建一个只能访问"当前用户"和"行政区划"两个接口的应用。
|
||
|
||
### 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` 更新秘钥
|