# Python SDK 接入

使用标准库Python客户端连接本机模拟网关，显式传入客户Key、查询账户与用量、报价、最高TEST价格与幂等编号。

把本地模拟数据送进你的研究脚本。只需一个SDK文件，报价与执行状态都以普通字典返回。

运行范围：NO PIP DEPENDENCIES

## 对应能力

- [获取 X 账号资料](https://datanavoapi.com/apis/x/users/get/)：x.users.get，返回 data.item，不支持分页，客户成功请求1 TEST。

## 准备本机服务与客户 Key

先在完整DataNavoAPI项目中运行 npm run local，确认网站地址为 http://127.0.0.1:4321。SDK固定连接本机，始终使用 simulated 模式。

注册本地账户，创建允许 x.users.get 的客户 Key，并通过模拟收银台取得 TEST 点数。可以同时设置日/月/总消费预算，轮换Key也不会清零。

[创建客户 Key](https://datanavoapi.com/account/keys/)

[本地模拟收银台入口](https://datanavoapi.com/account/billing/)

## 下载一个文件即可使用

下载guanliu.py，与connect.py放在同一个目录，使用Python3.9或更高版本。SDK只使用标准库，不需要安装pip包。

SDK固定使用127.0.0.1，不读取HTTP代理配置、不跟随重定向。网站端口改变时显式修改构造函数中的port。

[下载 guanliu.py](https://datanavoapi.com/sdk/guanliu.py)

## 先读取报价，再选择是否执行

将下方保存为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，不能当作执行失败或自动换编号重发。

[网页只读回执检查](https://datanavoapi.com/tools/request-inspector/)

[CLI 查询同一回执](https://datanavoapi.com/integrations/cli/#receipts)

## 按响应状态决定下一步

200是模拟成功；202是处理中，不自动轮询。401/403检查Key和scope；402查看最高单价、余额与预算；409表示编号已经用于不同的参数或场景。

502/504是已返回的模拟失败或超时，回执记录释放情况。运输异常的 outcomeUnknown / outcome_unknown=true 表示结果未确认，不能据此声称没有执行或扣点。

SDK不自动重试或翻页。报价失败属于未执行，错误的未知结果标志为false；quote本身不会消费点数。

[查看执行与结算](https://datanavoapi.com/account/executions/)

[预算合同说明](https://datanavoapi.com/docs/#budgets)

## 手动分页，逐页保留请求编号

搜索或评论的成功响应可含 body.page.next_cursor。需要下一页时，复制原params并加入cursor，使用新的幂等编号再call；同一页重放继续用该页编号。

SDK没有全局最高价格设置。每次手动call下一页都显式传maxCredits或max_credits。新页独立扣TEST；已完成回执重放不新增扣点。

本页x.users.get示例没有分页。请先从对应能力文档确认paginated，再把相应参数应用到分页调用。

[能力目录](https://datanavoapi.com/apis/)

[统一对象字段](https://datanavoapi.com/docs/objects/)

## 不要丢掉未知结果标志

GuanliuError.code是固定安全错误码，outcome_unknown表明执行是否可能已经送达。错误文本不会回显客户Key、认证头或底层网络异常。

HTTP业务失败由status和body返回；代码异常才进入except。不要把所有异常统一记为“未扣点”，也不要无限循环创建新编号。

[阅读执行记录](https://datanavoapi.com/account/executions/)

## 核对已经保存的真实请求

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 占用幂等编号时不泄露其回执。

[live 只读接入说明](https://datanavoapi.com/mcp/#live-read)

[账户真实调用记录](https://datanavoapi.com/account/live-usage/)

## 下一步

[改用JavaScript](https://datanavoapi.com/integrations/javascript/)

[连接MCP](https://datanavoapi.com/integrations/mcp-stdio/)

[任务点数估算](https://datanavoapi.com/pricing/)

真实API和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。

## 机器接入与数据说明

演示固定返回虚构样本，请检查 meta.mode，不得作为实时市场事实。MCP 默认 demo，可显式配置客户 Key 使用 simulated；SDK 固定模拟模式。模拟调用只消耗 TEST_CREDIT，真实供应商和支付保持关闭。

[能力合同](https://datanavoapi.com/catalog.json)

[OpenAPI](https://datanavoapi.com/openapi.json)

[Agent 指引](https://datanavoapi.com/agents.md)
