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