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

使用上传、等待与下载助手

本页内容

SDK 助手负责组合多次接口调用,帮助您恢复文件上传、等待已有任务和校验下载。先选要完成的任务,再保存业务状态并调用对应助手。

选择助手

接口方法完成一次明确的 API 操作;助手把分页、任务查询或文件分片组织成一个有上限的流程。上传助手不会自动开通服务或提交签名,等待助手不会创建任务,下载助手不会扩大原包或签名包权限。

任务适用场景接入要点
恢复安装包上传首次传输或进程重启后继续传输。先保存创建键和文件身份,取得上传任务 ID 后立即持久保存。
等待已有任务等待上传校验或签名处理。设置次数与时间上限,等待结束后检查业务状态。
逐页遍历读取多页历史版本或任务。限定页数,使用返回游标,逐条处理而不无限积累。
校验下载在自己的服务端取得指定版本。准备完整下载回执、独立可信摘要和存储来源白名单。

前提条件

  1. 按对应语言指南初始化 Client,先完成一次只读查询。
  2. 准备完整业务应用 ID。新应用先创建预留,更新使用已有应用 ID;签名等待还需要原签名任务 ID。
  3. 为每次独立上传保存创建幂等键、原文件路径、大小及摘要。恢复前核对同一文件,不能只比较名称或大小。
  4. 准备可持久提交的业务存储。下面的上传函数要求调用方传入保存任务 ID 的回调;回调失败时必须抛错或返回错误,不能用打印 ID 代替提交。

示例是可复用的业务函数,接收已初始化的 Client 和业务存储回调。Client 的完整配置与异常类型见所选语言入门;代码本身不保存 Secret,也不提供自动成功的数据库占位实现。

上传与恢复安装包

  1. 新传输时先提交创建键和文件身份,再调用上传函数;尚无上传任务 ID 时传空值。
  2. 助手取得任务后调用保存回调。在回调提交成功之后,才继续申报和传输分片。
  3. 发生中断后,从业务存储读取原上传任务 ID,核对文件身份,再调用同一函数恢复,不重新创建应用或上传任务。
  4. 助手返回后检查上传状态。返回 validating 说明仍在校验;继续查询原任务,等待 succeeded 与版本 ID。
Python

保存为 upload_example.py,与初始化 Client 的业务入口一起使用。

Python
from cloudsign.uploader import upload_file


def upload_package(client, app, file_path, create_key, upload_id, save_upload_id):
    if not callable(save_upload_id):
        raise ValueError("A durable task-ID callback is required")
    return upload_file(
        client, app, file_path,
        idempotency_key=create_key, upload_id=upload_id,
        on_upload=save_upload_id,
    )
PHP

保存为 upload_example.php,与初始化 Client 的业务入口一起使用。

PHP
<?php
require_once __DIR__ . '/cloudsign-sdk/php/Client.php';
require_once __DIR__ . '/cloudsign-sdk/php/Uploader.php';

use Cloudsign\Sdk\Client;
use Cloudsign\Sdk\Uploader;

function uploadPackage(Client $client, string $app, string $path,
                       ?string $createKey, ?string $uploadId,
                       callable $saveUploadId): array
{
    return Uploader::file($client, $app, $path, $createKey, $uploadId, $saveUploadId);
}
Node.js

保存为 upload_example.mjs,与初始化 Client 的业务入口一起使用。

Node.js
import { uploadFile } from './cloudsign-sdk/node/uploader.mjs';

export async function uploadPackage(client, app, filePath, createKey,
                                    uploadId, saveUploadId) {
    if (typeof saveUploadId !== 'function') {
        throw new Error('A durable task-ID callback is required');
    }
    return uploadFile(client, app, filePath, {
        idempotencyKey: createKey, uploadId, onUpload: saveUploadId,
    });
}
Go

保存为 upload_example.go,与初始化 Client 的业务入口一起使用。

Go
package main

import (
    "context"
    "errors"
    cloudsign "cloudsign/sdk"
)

func uploadPackage(ctx context.Context, client *cloudsign.Client,
    app, path, createKey, uploadID string,
    saveUploadID func(string) error) (cloudsign.Result, error) {
    if saveUploadID == nil {
        return cloudsign.Result{}, errors.New("a durable task-ID callback is required")
    }
    return client.UploadFile(ctx, app, path, cloudsign.UploadOptions{
        IdempotencyKey: createKey, UploadID: uploadID, OnUpload: saveUploadID,
    })
}
Java

保存为 UploadExample.java,与初始化 Client 的业务入口一起使用。

Java
import com.cloudsign.openapi.Client;
import com.cloudsign.openapi.Helpers;
import java.io.IOException;
import java.nio.file.Path;
import java.util.Objects;
import java.util.function.Consumer;

public final class UploadExample {
    public static Client.Result uploadPackage(Client client, String app, Path path,
            String createKey, String uploadId, Consumer<String> saveUploadId)
            throws IOException {
        Objects.requireNonNull(saveUploadId, "A durable task-ID callback is required");
        return Helpers.uploadFile(client, app, path,
                new Helpers.UploadOptions(createKey, uploadId, saveUploadId));
    }
}

Python 也可直接使用带私有状态文件的企业签名上传工具。Rust 使用 begin_upload_file 取得会话后先保存检查点,再调用会话的 transfer 方法,具体类型与生命周期见Rust 源码包 README;C 的完整检查点流程见恢复完整上传。

单片内容最多 32 MiB;SDK 助手的文件上限为 16 GiB,实际仍受账号和本站存储配置限制。助手检查调用期间的文件变化,跨进程恢复前的文件身份核对由业务端负责。

等待并取得签名结果

下面函数只接收已有任务 ID,不提交签名。先等待任务结束,再明确检查 succeeded,最后用该任务查询准确产物。旧任务无可信关联或产物已清理时直接报告结果不可用,不改取应用的最新版本。

Python

保存为 wait_example.py,与初始化 Client 的业务入口一起使用。

Python
import re


def signed_version(client, app, job):
    task = client.wait_job(app, job, interval_seconds=2,
                           maximum_polls=30, timeout_seconds=90)
    if task["data"]["status"] != "succeeded":
        raise RuntimeError("Signing task did not succeed")
    result = client.get_job_result(app, job)["data"]
    version = result.get("signed_version")
    if (result["app_id"] != app or result["job_id"] != job
            or result["result_state"] != "available" or not isinstance(version, dict)
            or not isinstance(version.get("id"), str)
            or not re.fullmatch(r"V[a-f0-9]{32}", version["id"])):
        raise RuntimeError("Signed result is unavailable")
    return version["id"]
PHP

保存为 wait_example.php,与初始化 Client 的业务入口一起使用。

PHP
<?php
require_once __DIR__ . '/cloudsign-sdk/php/Client.php';

use Cloudsign\Sdk\Client;

function signedVersion(Client $client, string $app, string $job): string
{
    $task = $client->waitJob($app, $job, 2, 30, 90);
    if ($task['data']['status'] !== 'succeeded') {
        throw new RuntimeException('Signing task did not succeed');
    }
    $result = $client->getJobResult($app, $job)['data'];
    $version = $result['signed_version'];
    if ($result['app_id'] !== $app || $result['job_id'] !== $job
        || $result['result_state'] !== 'available' || !is_array($version)
        || !is_string($version['id'] ?? null) || !preg_match('/^V[a-f0-9]{32}$/D', $version['id'])) {
        throw new RuntimeException('Signed result is unavailable');
    }
    return $version['id'];
}
Node.js

保存为 wait_example.mjs,与初始化 Client 的业务入口一起使用。

Node.js
export async function signedVersion(client, app, job) {
    const task = await client.waitJob(app, job, {
        intervalSeconds: 2, maximumPolls: 30, timeoutSeconds: 90,
    });
    if (task.data.status !== 'succeeded') {
        throw new Error('Signing task did not succeed');
    }
    const { data } = await client.getJobResult(app, job);
    const id = data.signed_version?.id;
    if (data.app_id !== app || data.job_id !== job || data.result_state !== 'available'
        || typeof id !== 'string' || !/^V[a-f0-9]{32}$/.test(id)) {
        throw new Error('Signed result is unavailable');
    }
    return id;
}
Go

保存为 wait_example.go,与初始化 Client 的业务入口一起使用。

Go
package main

import (
    "context"
    "errors"
    "regexp"
    "time"
    cloudsign "cloudsign/sdk"
)

func signedVersion(ctx context.Context, client *cloudsign.Client,
    app, job string) (string, error) {
    task, err := client.WaitJob(ctx, app, job, 2*time.Second, 30)
    if err != nil { return "", err }
    if task.Data["status"] != "succeeded" {
        return "", errors.New("signing task did not succeed")
    }
    result, err := client.GetJobResult(ctx, app, job)
    if err != nil { return "", err }
    version, ok := result.Data["signed_version"].(map[string]any)
    if result.Data["app_id"] != app || result.Data["job_id"] != job || result.Data["result_state"] != "available" || !ok {
        return "", errors.New("signed result is unavailable")
    }
    id, ok := version["id"].(string)
    if !ok || !regexp.MustCompile(`^V[a-f0-9]{32}$`).MatchString(id) {
        return "", errors.New("signed result is unavailable")
    }
    return id, nil
}
Java

保存为 WaitExample.java,与初始化 Client 的业务入口一起使用。

Java
import com.cloudsign.openapi.Client;
import com.cloudsign.openapi.Helpers;
import java.io.IOException;
import java.time.Duration;
import java.util.Map;

public final class WaitExample {
    public static String signedVersion(Client client, String app, String job)
            throws IOException {
        var task = Helpers.waitJob(client, app, job, Duration.ofSeconds(2), 30);
        if (!"succeeded".equals(task.data().get("status"))) {
            throw new IOException("Signing task did not succeed");
        }
        var result = client.getJobResult(app, job).data();
        if (!app.equals(result.get("app_id")) || !job.equals(result.get("job_id"))
                || !"available".equals(result.get("result_state"))) {
            throw new IOException("Signed result is unavailable");
        }
        if (!(result.get("signed_version") instanceof Map<?, ?> version)
                || !(version.get("id") instanceof String id)
                || !id.matches("V[a-f0-9]{32}")) {
            throw new IOException("Signed result is unavailable");
        }
        return id;
    }
}

示例采用每 2 秒一次、最多 30 次的查询。PHP、Python 和 Node.js 另设置 90 秒总时间预算;Go 与 Java 按次数和间隔限制,并支持 context 取消或线程中断。达到任一上限不会取消服务端任务,应保留原任务 ID 稍后继续。

等待上传使用 waitUpload / wait_upload / WaitUpload 等对应方法,检查的是 state,而不是签名任务的 status。Rust 使用 WaitOptions;C 的等待参数和释放方式见C SDK 等待说明。

遍历历史版本

语言对应助手处理方式
PythonClient.iter_versions同步生成器,逐条处理记录。
PHPClient::iterateVersionsGenerator,使用 foreach 逐条读取。
Node.jsClient.iterateVersions异步迭代器,使用 for await。
Gocloudsign.Walk传入取页与处理记录的回调,使用 context 取消。
JavaHelpers.walk传入 Page 与 Visit 回调,错误向调用方传播。
Rust / C各语言的分页对象或助手按对应语言的资源生命周期说明处理。

显式设置页数上限,翻页时保持产品、应用和筛选条件不变。游标缺失、重复或已经失效时停止并处理错误;不要自己递增版本 ID。逐页调用示例见分页查询与等待异步任务。

下载与校验文件

  1. 先确定准确的版本 ID 和包类型,并通过接口取得下载回执。传给文件助手的是响应 data 中的完整回执,不是最外层响应或单独的 ticket。
  2. 从独立可信记录取得此文件的 SHA-256,从自己的配置读取精确 HTTPS 存储来源白名单。当前 API 回执不提供可信安装包摘要。
  3. 选择已有私有目录中的新目标文件名,调用助手核对有效期、文件大小与摘要。目标已经存在时保留原文件。
  4. 校验成功后再把文件交给后续程序。地址过期或 ticket=null 时,明确决定是否重新申请下载凭证。
Python

保存为 download_example.py,与初始化 Client 的业务入口一起使用。

Python
from cloudsign.downloader import download_package


def download_version(receipt_data, destination, trusted_sha256, trusted_origins):
    return download_package(
        receipt_data, destination,
        expected_sha256=trusted_sha256,
        allowed_origins=trusted_origins,
        timeout_seconds=120,
    )
语言文件助手必需的业务输入
Pythondownload_package完整回执、目标路径、独立可信 SHA-256、受信 HTTPS 来源及有界超时。存储请求不附带 API Secret、Authorization 或 Cookie。
PHPDownloader::save
Node.jsdownloadPackage
Gocloudsign.DownloadPackage
JavaDownloader.save
Rustdownload_package
Ccloudsign_download_package

Python 示例中的参数由调用方提供。其他语言保持相同业务输入,参数类型和取消方式见包内对应助手;C 另见下载与校验安装包。没有独立可信摘要时,不能用下载后自己计算的摘要冒充预期值。

处理失败和中断

情况如何继续
保存任务 ID 失败停止后续传输,修复业务存储,用原请求和幂等键恢复取得的任务。
网络中断或等待超时读取原任务状态;保留原 ID、创建键、文件身份和检查点,不另起签名或付款。
存储传输成功但校验未完成等待上传 state=succeeded 且有 version_id。存储 2xx、分片确认与整包校验是不同阶段。
签名失败、旧结果缺失或被清理保留准确任务及错误信息,向使用者说明;需要新产物时明确发起另一项签名。
摘要不符或下载目标已存在保留已有文件,核对版本、可信摘要与目标路径。不要自动覆盖或关闭校验。

记录 HTTP 状态、错误码、request_id 和相关业务 ID,隐藏 Secret、短期地址和设备明细。SDK 更新前的检查点保留与回退步骤见版本、支持范围与升级。