Python SDK 接入
把本地模拟数据送进你的研究脚本。只需一个SDK文件,报价与执行状态都以普通字典返回。
使用标准库Python客户端连接本机模拟网关,显式传入客户Key、查询账户与用量、报价、最高TEST价格与幂等编号。
对应能力
准备本机服务与客户 Key
先在完整DataNavoAPI项目中运行 npm run local,确认网站地址为 http://127.0.0.1:4321。SDK固定连接本机,始终使用 simulated 模式。
注册本地账户,创建允许 x.users.get 的客户 Key,并通过模拟收银台取得 TEST 点数。可以同时设置日/月/总消费预算,轮换Key也不会清零。
下载一个文件即可使用
下载guanliu.py,与connect.py放在同一个目录,使用Python3.9或更高版本。SDK只使用标准库,不需要安装pip包。
SDK固定使用127.0.0.1,不读取HTTP代理配置、不跟随重定向。网站端口改变时显式修改构造函数中的port。
先读取报价,再选择是否执行
将下方保存为connect.py,在本机环境中设置GUANLIU_CUSTOMER_API_KEY。运行python3 connect.py只报价;确认后加--execute执行一次模拟调用。
本例以1 TEST上限查询演示账号。params与idempotency_key由调用方保存;修改参数开始新任务时换编号,重放原任务时不变。
import os
import sys
from guanliu import GuanliuClient, GuanliuError
client = GuanliuClient(os.environ['GUANLIU_CUSTOMER_API_KEY'], port=4321)
capability = 'x.users.get'
params = {'username': 'guanliu_demo'}
idempotency_key = 'py-account-sample-001'
try:
quote = client.quote(capability, params, max_credits=1)
print('quote', quote['status'], quote['body'])
if ('--execute' in sys.argv and quote['status'] == 200
and quote['body']['data']['eligible']):
result = client.call(
capability, params, idempotency_key=idempotency_key,
scenario='success', max_credits=1
)
print('call', result['status'], result['body'])
# 202仍在处理;不要自动换编号或循环重试。
except GuanliuError as error:
print(error.code, error.outcome_unknown)
# True表示执行结果未知。保留原编号、参数和场景。
在脚本中查看账户与用量
将下方保存为account.py,运行python3 account.py。它是独立只读示例;客户Key仍从本机进程环境读取。
account()直接读取余额、当前Key概要、预算与当日请求额度;usage(filters)读取当前Bearer Key的用量。两者不先拉目录、不执行、不预留或扣点,不需要幂等编号。
钱包属于账户,所有Key共享;预算随轮换组继承;用量只属于当前Key,新Key不继承旧Key的用量列表。用量是已保存计费流水,不是每次重试次数或所有未完成请求。
usage可筛选status(all/success/failure)、capability和UTC日期from/to。page为1–1,000,000整数,pageSize为20/50/100;Python使用相同字典字段名。默认第1页、20条,不自动翻页,不接受keyId/userId等身份覆盖。
预算按执行准入时间、用量按记录时间计算,跨日完成时可能不一致。返回金额为TEST_CREDIT,非真实供应商数据;只读失败的outcomeUnknown/outcome_unknown始终为false。
import os
from guanliu import GuanliuClient, GuanliuError
client = GuanliuClient(os.environ['GUANLIU_CUSTOMER_API_KEY'], port=4321)
try:
account = client.account()
usage = client.usage({'status': 'all', 'page': 1, 'pageSize': 20})
print('account', account['status'], account['body'])
print('usage', usage['status'], usage['body'])
except GuanliuError as error:
print(error.code, error.outcome_unknown)
# 只读失败始终为False,不会触发执行或自动重试。
只读查询执行状态与已保存结果
calls(filters)列出当前Key的模拟执行;receipt(requestId)读取单次状态;result(requestId)读取已保存结果。它们直接GET /v1/calls及详情路径,不恢复超时记录、不续租、不重发,也不再扣TEST。
calls使用state筛选all/pending/succeeded/failed/timed_out/interrupted,以及capability、UTC日期from/to、page和pageSize。调用按准入时间筛选;usage按用量记录时间筛选。
result外层HTTP200表示读取成功;data.response.status保留原执行状态,可能是502或504。pending尚无保存结果时返回409 call_result_pending,不能当作执行失败或自动换编号重发。
按响应状态决定下一步
200是模拟成功;202是处理中,不自动轮询。401/403检查Key和scope;402查看最高单价、余额与预算;409表示编号已经用于不同的参数或场景。
502/504是已返回的模拟失败或超时,回执记录释放情况。运输异常的 outcomeUnknown / outcome_unknown=true 表示结果未确认,不能据此声称没有执行或扣点。
SDK不自动重试或翻页。报价失败属于未执行,错误的未知结果标志为false;quote本身不会消费点数。
手动分页,逐页保留请求编号
搜索或评论的成功响应可含 body.page.next_cursor。需要下一页时,复制原params并加入cursor,使用新的幂等编号再call;同一页重放继续用该页编号。
SDK没有全局最高价格设置。每次手动call下一页都显式传maxCredits或max_credits。新页独立扣TEST;已完成回执重放不新增扣点。
本页x.users.get示例没有分页。请先从对应能力文档确认paginated,再把相应参数应用到分页调用。
不要丢掉未知结果标志
GuanliuError.code是固定安全错误码,outcome_unknown表明执行是否可能已经送达。错误文本不会回显客户Key、认证头或底层网络异常。
HTTP业务失败由status和body返回;代码异常才进入except。不要把所有异常统一记为“未扣点”,也不要无限循环创建新编号。
核对已经保存的真实请求
v0.28 增加明确的 live 只读入口。JavaScript / Python 使用 GuanliuLiveReadClient;CLI 使用 --mode live;stdio MCP 使用 GUANLIU_MCP_MODE=live。默认模拟模式保持原行为。
只读取当前 gl_live_ Key 的账户免费授权、用量、回执与保存结果。MCP 仅提供 find、describe、account,account 的 what=balance/usage/calls/standing/receipt/result;不执行新的请求,也不充值或支付。
pending 与 unknown 不自动重试。免费预留按供应商和单位分开,实际供应商成本未知;同账户其他 Key 占用幂等编号时不泄露其回执。
下一步
真实API和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。