纯协议调用(/v1/ilink/*,不经过 WMPF)
/v1/ilink/* 是 WeAppDev 的纯协议平面:Rust 用当前登录账号的会话直发微信 CGI—— 不经过小程序容器、不进捕获/改写/插件链,没有小程序在前台也能用。
适用场景:拿登录 code、取加密通道 key/iv、取插件 HostSign、取云开发凭证、 纯协议直调云函数,以及把整套调用搬进你自己的服务端。
一、统一返回信封
所有 /v1/ilink/* 接口返回同一种结构(对齐应用宝协议的 APIResponse):
json
{
"ok": true, // 业务是否成功
"code": 0, // 上游 ret/errcode;0 = 成功
"category": "ok", // ok | risk | usage-record | upstream | auth | input | internal
"retryable": false, // 原样重试是否有意义
"message": "success",
"data": { } // 全部业务数据都在这里,明文(绝不返回 base64)
}ok:false时先看category(下面第五节的风控表)再决定下一步;data里全是解析好的字段:protobuf 响应已按协议拆成base_response/code等, JSON 响应已解出payload(业务 JSON)与credential(凭证)。
二、接口目录
| 需求 | REST(POST /v1/ilink/…) | MCP wad_ilink action |
|---|---|---|
等价 wx.login() 拿 code | js-login | js-login |
| 用户信息加密通道 key/iv | get-user-encrypt-key | get-user-encrypt-key |
| 插件 HostSign | verify-plugin | verify-plugin |
| 云网关 V3 凭证 | cloud/get-cloud-gateway-v3-token-key | get-cloud-gateway-v3-token-key |
| 云托管凭证 | cloud/get-cloud-container-token-key | get-cloud-container-token-key |
| 任意云开发 API(函数/库/存储) | js-operate-wx-data | js-operate-wx-data |
| 同上,便捷形态 | js-operate-wx-data-by-api | js-operate-wx-data-by-api |
| 修复 code 过期 / 加最近使用 | update-wxa-usage-record | update-wxa-usage-record |
| 小程序实时档案(名称/头像/签名) | app_info | app_info |
三、决策总表(云开发资源)
| 资源 | 方式 A:Native 直发(依赖 API Server) | 方式 B:取凭证后完全脱离 WeAppDev |
|---|---|---|
| 云网关 V3 | js-operate-wx-data-by-api(qbase_commapi 信封) | ✅ cloud/get-cloud-gateway-v3-token-key 取 token/key,用 wxcloud-gateway-sdk 自己构造请求 |
| 云托管 | 同上 | ✅ cloud/get-cloud-container-token-key 取 key/url,用 ContainerSyncClient(支持流式) |
| 云函数 | 仅 js-operate-wx-data(-by-api)(tcbapi_slowcallfunction_v2) | ❌ 无独立凭证 |
| 云数据库 / 存储 | 仅 js-operate-wx-data(-by-api)(换 qbase_api_name) | ❌ 同上 |
一句话:云网关和云托管能取凭证自己跑;云函数和云数据库借 WeAppDev 的通道发。
四、实测示例(全部明文)
4.1 js-login —— 换登录 code
bash
curl -s -X POST http://127.0.0.1:9400/v1/ilink/js-login \
-H 'Content-Type: application/json' -d '{"appid":"wx1234567890abcdef"}'json
{ "ok": true, "code": 0, "category": "ok", "message": "success",
"data": { "cgi": "/cgi-bin/mmbiz-bin/js-login", "base_response": {"ret": 0},
"msg": {"ret": 0, "msg": "ok"},
"code": "0b3fILHa1SusRM012MHa1jAPQr1fILHB" } }data.code 即登录 code(约 5 分钟有效、一次性)。
4.2 直调云函数(真机实测,拿到明文业务数据)
第一步:绑定环境鉴权(关键前置,跳过会拿到空业务体):
bash
curl -s -X POST http://127.0.0.1:9400/v1/ilink/js-operate-wx-data-by-api \
-H 'Content-Type: application/json' \
-d '{"appid":"wx1234567890abcdef","qbase_api_name":"tcbapi_getenvauth",
"data":{"env":"cloud1-xxxxxxxxxxxxxxxx"}}'第二步:调云函数(注意 data 要二次字符串化):
bash
curl -s -X POST http://127.0.0.1:9400/v1/ilink/js-operate-wx-data-by-api \
-H 'Content-Type: application/json' \
-d '{"appid":"wx1234567890abcdef",
"qbase_api_name":"tcbapi_slowcallfunction_v2",
"data":{"function_name":"myFn",
"data":"{\"action\":\"getList\",\"month\":\"2026-11\"}",
"action":1,"scene":1,
"call_id":"1795166000000-0.1","cloudid_list":[]},
"env":"cloud1-xxxxxxxxxxxxxxxx"}'返回(节选):
json
{ "ok": true, "code": 0,
"data": { "payload": { "status": 1, "service_errcode": 0,
"baseresponse": {"errcode": 0},
"data": "{\"code\":0,\"message\":\"ok\",\"data\":{…明文业务数据…}}" } } }要点(实测踩坑):
- 信封
api_name恒为qbase_commapi,目标 API 放qbase_api_name(-by-api便捷形态会帮你组好这一切); qbase_req必须是 JSON 字符串而不是对象;云函数载荷里function_name与data同级、data二次字符串化;- 云函数先调一次
tcbapi_getenvauth绑环境,否则status:0且业务体为空; - 凭证类接口的返回在
data.credential = {token, key, iat, exp, rid}。
4.3 取云网关凭证 → 自己发请求
bash
curl -s -X POST http://127.0.0.1:9400/v1/ilink/cloud/get-cloud-gateway-v3-token-key \
-H 'Content-Type: application/json' \
-d '{"appid":"wx1234567890abcdef","domain":"xxx.service.tcloudbase.com"}'
# → data.credential = {"token":"...","key":"...","iat":...,"exp":...,"rid":"..."}bash
pip install wxcloud-gateway-sdk # 源码: github.com/RYF5584/wxcloud-gateway-sdkpython
from wxcloud_gateway_sdk import GatewaySyncClient
c = GatewaySyncClient(key=KEY, domain=DOMAIN, token=TOKEN) # AES-CBC+Snappy+Protobuf 自动
r = c.post("/api/order/list", json={"page": 1})四个客户端:GatewaySyncClient / GatewayAsyncClient / ContainerSyncClient / ContainerAsyncClient;容器侧另有 send_stream_request(流式)。离线解包用 decode_response(...) 或 API 内置 POST /v1/cloud/decode。
4.4 取云托管凭证
bash
curl -s -X POST http://127.0.0.1:9400/v1/ilink/cloud/get-cloud-container-token-key \
-H 'Content-Type: application/json' -d '{"appid":"wx1234567890abcdef"}'五、风控码对照表(重要)
code | category | 含义 | 处置 |
|---|---|---|---|
-12030 | risk | 账号级风控:该账号纯协议全受限,所有小程序理论上都打不开;微信客户端本身正常,电脑端应用宝登录也正常,只是协议链路不可用;可能自行恢复 | 停止重试,等待恢复或换账号后再用单次轻量 js-login 探测 |
-12028 | risk | 小程序级风控,分两种:① 临时限频,过一会儿恢复;② 永久小程序级风控(少见)——任何账号调它的 js-login/云托管/云网关/云函数都返回 -12028,但微信端正常 | 换一个账号试同一个小程序:也报 -12028 即视为永久,放弃纯协议、改走容器内运行时捕获 |
61010 | usage-record | code 已过期:小程序不在账号「最近使用」里,签发的 code 立即失效 | js-login 内部已自动调 update-wxa-usage-record(加最近使用)并重试一次(见 data.healed);也可手动调 update-wxa-usage-record 后重试 |
其余非 0 code 归为 upstream,message 带原始 ret。
六、注意
- 凭证有有效期(
data.credential.exp),过期重新取; - 云函数返回的业务体在
data.payload.data(JSON 字符串),API 同时给出解析好的data.dataParsed; app_info拿到的username(gh_开头)是update-wxa-usage-record的寻址键;- 不要把凭证写进前端代码或公开仓库。