跳转到主要内容
1签 (OneSign)

SDK 版本、支持范围与升级

本页内容

接入或升级 SDK 前,先核对运行环境、版本和实际需要的能力。本页说明源码包的交付方式、环境限制,以及保留原任务的升级步骤。

选择接入方式

服务端项目使用与项目语言一致的 SDK。浏览器、Vue、iOS 和安卓应用通过自己的后端或已登记并获准的 OAuth 接入;Java 服务端包不能直接视为安卓 SDK。

当前交付源码预览和本地包配置,尚未正式发布到公共包仓库。请从本站下载并固定源码包,不要据本地包名直接假定 Composer、npm、PyPI 或 Maven 中已有同名官方版本。

核对版本和环境

当前六种服务端 SDK 属于 1.26.0-preview.1 预览系列;Python 使用 alpha 版本格式,Java 使用 SNAPSHOT 格式。C 单独使用 0.8.0-preview.1,升级时分别核对。接口定义版本为 1.22.0-preview.1。

语言源码要求开始使用
Python3.10+下载与首次调用
PHP8.3+,启用 ext-curl下载与首次调用
Node.js / TypeScriptNode.js 20+下载与首次调用
Go1.22+下载与首次调用
JavaJDK 17+下载与首次调用
Rust1.88+,使用 Tokio下载与首次调用
CC11、CMake 3.20+,需原生依赖下载与首次调用

最低版本表示源码的运行基线。实际项目还要检查操作系统、TLS、扩展和文件系统权限。PHP 当前验证 8.3、8.4、8.5;C 的文件助手使用 Linux / POSIX 接口,其他系统可能返回 UnsupportedPlatform。原生库与依赖说明见对应语言指南。

下载后核对包内 SHA256SUMS,并独立保存源码包摘要与所用提交。包内清单用于发现文件损坏,不能单独证明一个不可信来源就是官方来源。

确认能力与限制

七种现有服务端 SDK 覆盖当前 57 个用户 API 操作。能否调用某个操作,仍由账号接入许可、动作、应用归属、来源 IP 和预算共同决定。更新 SDK 不会自动增加这些权限。

需要完成的任务使用方式需要另外确认
单次查询或写入使用具体接口对应的 SDK 方法。所属产品、完整资源 ID、JSON 字段和写入幂等键。
上传、等待或下载使用任务助手组合调用。原任务状态、文件身份、可信摘要和受信存储来源。
接收业务通知使用 SDK 验签并在持久事务提交后返回回执。受信订阅、回调密钥、去重和应用归属。
网页或移动端访问使用自己的后端或 OAuth。终端授权范围,且不内置长期 Secret。

上传使用统一入口:平台选择文件传输服务,SDK 按短期指令自动传输。业务代码无需选择存储厂商、配置存储账号或处理后台启用流程。

文件下载助手不覆盖已经存在的目标文件。请为每次独立下载选择新路径,并从可信业务记录取得预期摘要。

升级前准备

  1. 保存旧源码包、包配置、依赖锁文件及摘要,保留可回退的部署版本。
  2. 记录正在执行的应用 ID、上传任务 ID、签名任务 ID、报价 ID 和原幂等键。保留对应文件身份与请求内容,不把 Secret 或短期存储地址写入业务检查点。
  3. 阅读版本说明,确认新字段是否可空、默认行为是否变化,以及是否涉及 C 的类型或 ABI。C 预览升级后重新编译调用方。
  4. 在独立测试目录或预发布环境准备新包,保留原账号权限、来源 IP 和预算设置。

执行升级与验证

  1. 核对新包摘要,按语言指南安装。保留 Go 的本地模块配置、Rust 的 Cargo.lock 和 C 的配套头文件。
  2. 先执行身份查询,核对账号和权限,再查询一个自己的应用。记录 HTTP 状态与 request_id。
  3. 使用已有任务验证查询和恢复。等待超时后继续原任务,不通过重新提交签名、付款或核销来测试升级。
  4. 检查本项目实际使用的分页、空值、金额字符串、通知验签与文件助手,再逐步切换服务端实例。
  5. 确认请求正常后保留升级记录,按原策略处理旧版本和仍在执行的任务。

预览版本可能收紧非法输入或增加类型要求。升级前验证调用方,不能仅凭“编译成功”判断原有业务流程都已兼容。

回退与问题报告

发现兼容问题时先暂停新增写入,保留原资源和操作记录。恢复旧 SDK 后,先查询已有上传、签名、报价或回执,确认真实结果,再决定是否继续原操作。不要更换幂等键重复扣款。

提供 SDK 版本、运行环境、操作名、失败时间、HTTP 状态、错误码、request_id 和脱敏的最小复现。不要提交 Secret、安全令牌、开通密钥、带授权的链接或设备明细。接入排查步骤见接入常见问题。