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

提交签名与获取结果

本页内容

为已经上传并开通服务的企业签名应用创建签名任务。签名异步执行;请保存任务 ID,等待任务成功,再取得该任务实际生成的签名包版本。

前提条件

  • 上传任务已成功,保存了该应用可签名的最新原包版本 ID。
  • 已开通有效签名服务,且 API 应用有提交任务、查询任务和读取版本的权限。
  • 需要选择证书时,按证书与参数指南准备可用证书 ID。

开通、上传和保存参数都不会自动提交签名。签名提交时仍检查当前权益、证书、原包和权限。

步骤一:提交一次签名

为这次独立签名保存原包版本、可选证书和幂等键,再创建任务。收到任务 ID 后立即保存,后续查询使用它。

Python SDK
def submit_signature(client, app_id, original_version_id, write_key,
                     certificate_id=None):
    task = client.create_job(
        app_id, original_version_id, write_key,
        certificate_id=certificate_id,
    )["data"]
    return task["id"]  # 立即保存到业务记录,然后再查询任务。

同一操作网络重试使用原幂等键;确实需要再签一次时才创建新的操作。原包版本必须属于当前应用,不能把上一次生成的签名包当作原包提交。

步骤二:等待任务结束

调用 查询签名任务进度查询。使用 SDK 等待助手时,应设置次数和总时长上限;等待超时只表示客户端停止等待,任务可能仍在执行。

返回状态处理方式
terminal=false尚未结束,间隔查询原任务。进度仅用于展示。
terminal=true 且 status=succeeded签名成功,继续取得本任务的结果。
failed、cancelled 或 superseded任务已结束,但没有成功完成本次签名。读取错误或替代状态。

HTTP 200、任务已受理或进度达到 100%,都不能单独作为签名成功的依据。

步骤三:取得本次签名结果

调用 查询签名任务对应的准确产物。结果可用时,使用返回的 signed_version.id 申请下载。

Python SDK
def find_signed_version(client, app_id, job_id):
    result = client.get_job_result(app_id, job_id)["data"]
    if result["result_state"] != "available":
        return None  # 根据状态继续等待或处理失败,不改取“最新版本”。
    return result["signed_version"]["id"]
result_state含义与处理
pending任务仍在处理,继续查询。
available已取得该任务的准确签名版本。
not_produced本任务没有生成可用签名包,查看任务最终状态。
not_recorded旧任务没有可靠的产物关联,需人工核对。
removed对应产物已清理,无法下载该版本。

同一应用可能多次签名。不要用版本列表第一项代替任务结果;它可能属于其他任务。is_current=false 也不表示本次结果错误,可能只是后来发布了其他版本。

批量签名

批量提交签名任务一次接收 1–10 个不同应用。每项填写应用 ID、对应原包版本 ID和可选证书 ID,批次使用一个已保存的幂等键。

除批量权限 enterprise:CreateBatchJobs 外,每个应用都需要正常的提交权限和签名条件。受理后保存每项返回的任务 ID,分别等待和查询结果。某个任务执行成功不代表其他任务也成功。

恢复中断的操作

源码包中的签名工具会保存提交信息及任务 ID。可以先提交,再在中断后恢复:

签名工具
python enterprise_signing.py start --app "<应用ID>" --source "<原包版本ID>" --state signing.json
python enterprise_signing.py resume --state signing.json

已保存任务 ID 时直接查询原任务。提交响应丢失且尚无任务 ID时,工具只在 24 小时内使用原幂等键恢复;超过此限先用 列出应用签名任务找回记录。状态文件不要被多个进程同时使用,每次独立重签使用新的状态文件。

结果可用后继续下载签名包。若服务无效、证书不可用或输入版本过期,先解决原因,再明确发起新的操作。

相关接口