使用上传、等待与下载助手
本页内容
SDK 助手负责组合多次接口调用,帮助您恢复文件上传、等待已有任务和校验下载。先选要完成的任务,再保存业务状态并调用对应助手。
选择助手
接口方法完成一次明确的 API 操作;助手把分页、任务查询或文件分片组织成一个有上限的流程。上传助手不会自动开通服务或提交签名,等待助手不会创建任务,下载助手不会扩大原包或签名包权限。
| 任务 | 适用场景 | 接入要点 |
|---|---|---|
| 恢复安装包上传 | 首次传输或进程重启后继续传输。 | 先保存创建键和文件身份,取得上传任务 ID 后立即持久保存。 |
| 等待已有任务 | 等待上传校验或签名处理。 | 设置次数与时间上限,等待结束后检查业务状态。 |
| 逐页遍历 | 读取多页历史版本或任务。 | 限定页数,使用返回游标,逐条处理而不无限积累。 |
| 校验下载 | 在自己的服务端取得指定版本。 | 准备完整下载回执、独立可信摘要和存储来源白名单。 |
前提条件
- 按对应语言指南初始化 Client,先完成一次只读查询。
- 准备完整业务应用 ID。新应用先创建预留,更新使用已有应用 ID;签名等待还需要原签名任务 ID。
- 为每次独立上传保存创建幂等键、原文件路径、大小及摘要。恢复前核对同一文件,不能只比较名称或大小。
- 准备可持久提交的业务存储。下面的上传函数要求调用方传入保存任务 ID 的回调;回调失败时必须抛错或返回错误,不能用打印 ID 代替提交。
示例是可复用的业务函数,接收已初始化的 Client 和业务存储回调。Client 的完整配置与异常类型见所选语言入门;代码本身不保存 Secret,也不提供自动成功的数据库占位实现。
上传与恢复安装包
- 新传输时先提交创建键和文件身份,再调用上传函数;尚无上传任务 ID 时传空值。
- 助手取得任务后调用保存回调。在回调提交成功之后,才继续申报和传输分片。
- 发生中断后,从业务存储读取原上传任务 ID,核对文件身份,再调用同一函数恢复,不重新创建应用或上传任务。
- 助手返回后检查上传状态。返回 validating 说明仍在校验;继续查询原任务,等待 succeeded 与版本 ID。
Python
保存为 upload_example.py,与初始化 Client 的业务入口一起使用。
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
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 的业务入口一起使用。
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 的业务入口一起使用。
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 的业务入口一起使用。
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 的业务入口一起使用。
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
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 的业务入口一起使用。
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 的业务入口一起使用。
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 的业务入口一起使用。
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 等待说明。
遍历历史版本
| 语言 | 对应助手 | 处理方式 |
|---|---|---|
| Python | Client.iter_versions | 同步生成器,逐条处理记录。 |
| PHP | Client::iterateVersions | Generator,使用 foreach 逐条读取。 |
| Node.js | Client.iterateVersions | 异步迭代器,使用 for await。 |
| Go | cloudsign.Walk | 传入取页与处理记录的回调,使用 context 取消。 |
| Java | Helpers.walk | 传入 Page 与 Visit 回调,错误向调用方传播。 |
| Rust / C | 各语言的分页对象或助手 | 按对应语言的资源生命周期说明处理。 |
显式设置页数上限,翻页时保持产品、应用和筛选条件不变。游标缺失、重复或已经失效时停止并处理错误;不要自己递增版本 ID。逐页调用示例见分页查询与等待异步任务。
下载与校验文件
- 先确定准确的版本 ID 和包类型,并通过接口取得下载回执。传给文件助手的是响应 data 中的完整回执,不是最外层响应或单独的 ticket。
- 从独立可信记录取得此文件的 SHA-256,从自己的配置读取精确 HTTPS 存储来源白名单。当前 API 回执不提供可信安装包摘要。
- 选择已有私有目录中的新目标文件名,调用助手核对有效期、文件大小与摘要。目标已经存在时保留原文件。
- 校验成功后再把文件交给后续程序。地址过期或 ticket=null 时,明确决定是否重新申请下载凭证。
Python
保存为 download_example.py,与初始化 Client 的业务入口一起使用。
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,
)| 语言 | 文件助手 | 必需的业务输入 |
|---|---|---|
| Python | download_package | 完整回执、目标路径、独立可信 SHA-256、受信 HTTPS 来源及有界超时。存储请求不附带 API Secret、Authorization 或 Cookie。 |
| PHP | Downloader::save | |
| Node.js | downloadPackage | |
| Go | cloudsign.DownloadPackage | |
| Java | Downloader.save | |
| Rust | download_package | |
| C | cloudsign_download_package |
Python 示例中的参数由调用方提供。其他语言保持相同业务输入,参数类型和取消方式见包内对应助手;C 另见下载与校验安装包。没有独立可信摘要时,不能用下载后自己计算的摘要冒充预期值。
处理失败和中断
| 情况 | 如何继续 |
|---|---|
| 保存任务 ID 失败 | 停止后续传输,修复业务存储,用原请求和幂等键恢复取得的任务。 |
| 网络中断或等待超时 | 读取原任务状态;保留原 ID、创建键、文件身份和检查点,不另起签名或付款。 |
| 存储传输成功但校验未完成 | 等待上传 state=succeeded 且有 version_id。存储 2xx、分片确认与整包校验是不同阶段。 |
| 签名失败、旧结果缺失或被清理 | 保留准确任务及错误信息,向使用者说明;需要新产物时明确发起另一项签名。 |
| 摘要不符或下载目标已存在 | 保留已有文件,核对版本、可信摘要与目标路径。不要自动覆盖或关闭校验。 |
记录 HTTP 状态、错误码、request_id 和相关业务 ID,隐藏 Secret、短期地址和设备明细。SDK 更新前的检查点保留与回退步骤见版本、支持范围与升级。