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

4.1 KiB
Raw Blame History

使用指南

完整示例

场景:创建第三方应用访问权限

假设你需要为第三方合作方创建一个只能访问"当前用户"和"行政区划"两个接口的应用。

1. 准备工作

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. 创建认证

# 获取新秘钥
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. 绑定授权接口

# 绑定授权接口
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. 授权用户(可选)

如果需要记录调用方用户:

# 获取用户信息
user_resp = oauth.save_user_list(resp.data, [
    {"userId": "user_id_123", "userKey": "partner_user_1"},
])

5. 外部系统调用

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())

高级配置

启用签名验证

# 创建时启用签名
resp = oauth.create({
    "appId": "secure_app",
    "appName": "安全应用",
    "appSecret": app_secret,
    "verifySignature": 1,  # 启用签名验证
    "enabledMark": 1,
})

设置使用期限

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,
})

管理授权接口

# 查看当前授权
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: 如何限制第三方只能访问特定接口?

# 绑定时只指定允许的接口
oauth.bind_interfaces(oauth_id, ["di_id_1", "di_id_2"])

Q: 如何吊销一个应用的访问权限?

# 方式1:禁用
oauth.update({"id": oauth_id, "enabledMark": 0})

# 方式2:删除
oauth.delete(oauth_id)

Q: 如何查看接口调用情况?

# 获取调用日志
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 更新秘钥