C SDK:传输与确认单个分片
本页内容
自行调度上传时,发送一个已声明分片,并由业务 API 确认其保存结果。
适用场景
本页适用于已经自行调度分片、只想传输并确认其中一片的 C 项目。助手负责该片的传输校验,平台确认后才将它记为已完成。
如果您只需要上传完整 IPA 或 APK,优先使用 完整可恢复上传助手,由 SDK 处理分片顺序与恢复。调用方无需选择存储厂商。
前提条件
- 准备自己的业务应用、已有上传任务 ID 和已声明的分片。按产品授予
enterprise:UploadVersions或distribution:UploadVersions。 - 保存原文件、当前分片的偏移、大小和 SHA-256,以及本片确认操作的稳定幂等键。
- 已配置允许访问的 HTTPS 文件传输域名,并按 C SDK 入门准备 Linux / POSIX 运行环境。
操作步骤
- 按上传任务返回的布局确定当前分片,调用 申报分片摘要 声明其真实内容。
- 先调用 确认分片已上传 核对是否已保存。只有 404 / PartMissing 才申请凭证并补传。
- 取得 获取分片上传凭证 后,将凭证与独立保存的本片参数交给
cloudsign_upload_part。 - 传输成功或提示对象已存在后,仍用原确认键调用 completeUploadPart,核对序号、大小、摘要和 uploaded。
- 所有分片均确认后,再提交整个安装包校验。单片确认不代表版本已经保存。
运行示例
配置网站主域名、长期 AccessKey、CLOUDSIGN_STORAGE_ORIGIN 和本片已持久保存的 CLOUDSIGN_IDEMPOTENCY_KEY。下列变量均来自自己的上传记录。
命令行示例需要哪些配置
这些变量由自己的进程安全配置注入,不把 Secret 写进命令历史或源码。它们只配置客户端,不选择平台存储厂商。
| 变量 | 如何填写 |
|---|---|
CLOUDSIGN_BASE_URL | 网站 HTTPS 主域名 https://www.onesignios.com。 |
CLOUDSIGN_ACCESS_KEY_ID | 示例使用的长期 AccessKey ID。 |
CLOUDSIGN_ACCESS_KEY_SECRET | 同一组长期凭据的 Secret。 |
CLOUDSIGN_API_CA_FILE | 可选的 API CA 文件;默认使用系统 CA。 |
CLOUDSIGN_STORAGE_ORIGIN | 由独立可信配置确认的精确 HTTPS 文件传输来源,用于限制客户端可访问的目标。 |
CLOUDSIGN_STORAGE_CA_FILE | 可选的文件传输 CA 文件,不能用它关闭证书验证。 |
CLOUDSIGN_IDEMPOTENCY_KEY | 当前分片确认操作已经持久保存的幂等键。 |
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_upload_part_example "$APP_ID" "$UPLOAD_ID" "$PART_NUMBER" \
/srv/my-app/private/application.ipa "$PART_OFFSET" "$PART_SIZE" "$PART_SHA256"查看完整 upload-part-example.c 源码
/* Trusted-server CLI: resume one declared part; never finalize the whole upload. */
#include <cloudsign/openapi.h>
#include <cJSON.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int hex_id(const char *text,char prefix,size_t digits){
if(!text||strlen(text)!=digits+(prefix?1:0)||(prefix&&*text++!=prefix))return 0;
for(size_t i=0;i<digits;++i)if(!((text[i]>='0'&&text[i]<='9')||(text[i]>='a'&&text[i]<='f')))return 0;
return 1;
}
static int decimal(const char *text,uint64_t maximum,uint64_t *out){
uint64_t value=0;if(!text||!*text)return 0;
for(const char *p=text;*p;++p){if(*p<'0'||*p>'9'||value>maximum/10)return 0;value=value*10+(unsigned)(*p-'0');if(value>maximum)return 0;}
*out=value;return 1;
}
static int env_copy(char *out,size_t capacity,const char *name){
const char *value=getenv(name);if(!value||!*value||strlen(value)>=capacity)return 0;
memcpy(out,value,strlen(value)+1);return 1;
}
static int confirmed(const cloudsign_result *result,unsigned number,uint64_t size,const char *sha){
cJSON *root=cJSON_ParseWithLength(cloudsign_result_json(result),cloudsign_result_json_length(result));
const cJSON *data=cJSON_GetObjectItemCaseSensitive(root,"data");
const cJSON *part=cJSON_GetObjectItemCaseSensitive(data,"part_number"),*bytes=cJSON_GetObjectItemCaseSensitive(data,"size_bytes"),*hash=cJSON_GetObjectItemCaseSensitive(data,"sha256"),*uploaded=cJSON_GetObjectItemCaseSensitive(data,"uploaded");
int ok=cJSON_IsNumber(part)&&part->valuedouble==number&&cJSON_IsNumber(bytes)&&bytes->valuedouble==(double)size&&cJSON_IsString(hash)&&!strcmp(hash->valuestring,sha)&&cJSON_IsTrue(uploaded);
cJSON_Delete(root);return ok;
}
int main(int argc,char **argv){
cloudsign_credentials keys={0};cloudsign_client *client=NULL;cloudsign_result *result=NULL;
cloudsign_status status=CLOUDSIGN_INVALID_INPUT;int initialized=0,exit_code=1;uint64_t number=0,offset=0,size=0;
const char *origin=getenv("CLOUDSIGN_BASE_URL"),*storage=getenv("CLOUDSIGN_STORAGE_ORIGIN"),*idem=getenv("CLOUDSIGN_IDEMPOTENCY_KEY");
if(argc!=8||!hex_id(argv[1],'A',32)||!hex_id(argv[2],'U',32)||!decimal(argv[3],1024,&number)||!number||!decimal(argv[5],17179869184ULL,&offset)||!decimal(argv[6],33554432,&size)||!size||!hex_id(argv[7],0,64)){
fputs("Usage: cloudsign_upload_part_example APP_ID UPLOAD_ID PART_NUMBER SOURCE_PATH OFFSET SIZE SHA256\n",stderr);goto done;
}
if(!origin||!storage||!idem||!env_copy(keys.access_key_id,sizeof(keys.access_key_id),"CLOUDSIGN_ACCESS_KEY_ID")||!env_copy(keys.access_key_secret,sizeof(keys.access_key_secret),"CLOUDSIGN_ACCESS_KEY_SECRET"))goto done;
status=cloudsign_global_init();if(status!=CLOUDSIGN_OK)goto done;initialized=1;
cloudsign_options api={.origin=origin,.credentials=&keys,.ca_file=getenv("CLOUDSIGN_API_CA_FILE"),.timeout_ms=15000};
status=cloudsign_client_create(&api,&client);cloudsign_credentials_clear(&keys);if(status!=CLOUDSIGN_OK)goto done;
cloudsign_param path[]={{"app_id",argv[1]},{"upload_id",argv[2]},{"part_number",argv[3]}};
cloudsign_request probe={.path=path,.path_count=3,.body_json="{}",.idempotency_key=idem};
/* Reuse this exact stable key only for this U / N / SHA confirmation. */
status=cloudsign_complete_upload_part(client,&probe,&result);
if(status==CLOUDSIGN_OK)goto verify;
if(status!=CLOUDSIGN_API_ERROR||cloudsign_result_http_status(result)!=404||strcmp(cloudsign_result_error_code(result),"PartMissing"))goto done;
cloudsign_result_free(result);result=NULL;
cloudsign_request ticket={.path=path,.path_count=3};
status=cloudsign_get_upload_part_ticket(client,&ticket,&result);if(status!=CLOUDSIGN_OK)goto done;
const char *allowed[]={storage};cloudsign_uploaded_part uploaded;
cloudsign_upload_part_options options={.upload_id=argv[2],.part_number=(unsigned)number,.source_path=argv[4],.offset=offset,.size_bytes=size,.expected_sha256=argv[7],
.allowed_origins=allowed,.allowed_origin_count=1,.ca_file=getenv("CLOUDSIGN_STORAGE_CA_FILE"),.total_timeout_ms=120000};
status=cloudsign_upload_part(result,&options,&uploaded);if(status!=CLOUDSIGN_OK)goto done;
/* 2xx and duplicate-object hints require the same authoritative API check. */
cloudsign_result_free(result);result=NULL;
status=cloudsign_complete_upload_part(client,&probe,&result);if(status!=CLOUDSIGN_OK)goto done;
verify:
if(!confirmed(result,(unsigned)number,size,argv[7])){status=CLOUDSIGN_INVALID_RESPONSE;goto done;}
printf("%s uploaded\n",cloudsign_result_request_id(result));exit_code=0;
done:
if(exit_code)fprintf(stderr,"%s %s; RequestId: %s\n",cloudsign_status_name(status),cloudsign_result_error_code(result),cloudsign_result_request_id(result));
cloudsign_result_free(result);cloudsign_client_free(client);cloudsign_credentials_clear(&keys);
if(initialized)cloudsign_global_cleanup();return exit_code;
}
确认结果
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| 传输助手返回 OK | 该片完成了本次传输检查。 | 仍须调用平台确认,不能仅依据 HTTP 2xx。 |
| 确认返回 uploaded=true | 平台已确认该片暂存。 | 继续其他分片;全部确认后提交整个上传任务。 |
| CLI 退出 0 | 示例完成了当前分片的确认。 | 保存 request_id 和 uploaded;它不会替您完成整个上传任务。 |
already_exists 是重复对象提示,不是内容已获平台确认的证明。CLI 不创建应用或上传任务,也不自动声明分片、重试或提交签名。
参数与详细规则
本片参数与整个文件参数分别保存,不能把整包摘要或另一片的凭证用于当前分片。
| 参数或对象 | 表示什么 | 使用要点 |
|---|---|---|
| upload_id / part_number | 原上传任务 ID 与当前分片序号。 | 与该片凭证及任务实际 part_count 一致。 |
| source_path / offset / size_bytes | 可信原文件及当前片的字节范围。 | offset 从 0 开始;也可使用已提取的分片文件。 |
| expected_sha256 | 已向 API 声明的当前分片摘要。 | 不是整个安装包摘要。 |
查看完整参数、内存管理与运行边界
| 配置 / 输出 | 说明 |
|---|---|
upload_id / part_number | 来自可信恢复记录的 上传任务 ID 和 1–1024 分片序号,严格匹配 UploadPartTicket。还须遵循服务器为该 上传任务 ID 给出的实际 part_count。 |
source_path / offset / size_bytes | 本机可信普通文件及明确字节范围。分片 1 字节–32 MiB,源文件不超过 16 GiB;offset 从 0 开始。可使用整个安装包的偏移,也可传已提取分片并设 offset=0。此助手不推算整体文件布局。 |
expected_sha256 | 预先保存并已向 API 声明的当前分片 64 位小写 SHA-256,不能拿整个安装包摘要或存储响应摘要替代。 |
allowed_origins | 1–16 个独立配置的精确 HTTPS 源;不从凭证自动信任源,不使用通配符、IP 字面量、非 443 端口、路径或查询。DNS 与出口策略仍由接入方维护。 |
total_timeout_ms / cancelled / context | 总预算 1000–600000 ms,包含读取、摘要、回调和网络。同步回调须有界;本地文件系统与阻塞回调无法被强制中断,返回后仍检查预算。context 保持有效。 |
ca_file | 默认系统 CA,可从可信配置指定 CA 文件。证书、主机名与 TLS 1.2 最低版本验证始终开启。 |
cloudsign_uploaded_part | size_bytes、sha256 是本地快照的大小与摘要;http_status 为存储响应,already_exists 表示提供商重复对象提示。这些字段不是服务器已核验对象的证明,必须调用 API 确认。失败清空所有输出。 |
运行限制与错误处理
助手在回调前复制配置并验证完整凭证;通过固定文件描述符拒绝符号链接 / 非普通文件,读取分片并核对前后文件元数据、范围和摘要,再发送不可变快照。单次最多占用 32 MiB 分片缓冲,不把整个 16 GiB 包读入内存;不修改源文件。调用期间不要并发修改输入、结果对象或源文件。需要整个安装包不变性及进程恢复时,由接入服务持久管理文件身份和分片清单。
SDK 自动识别平台返回的短期传输指令,调用方无需识别存储厂商。独立 libcurl 连接不接收 API 凭据,不发送 AccessKey、SecurityToken、API 签名头、Cookie、netrc 或隐式代理。它只允许指定的上传方法、请求头或表单字段,并核对对象范围、大小、摘要、有效期及允许的传输域名。凭证须尚未过期且有效期不超过一小时;读取前及网络开始前均检查。
不跟随重定向、不自动重试、不续票,不接受未知头或认证注入;响应头和正文各限 64 KiB,拒绝压缩、重复或冲突的长度和编码。重复对象响应统一为 already_exists 提示,仍须调用 API 确认;其他失败响应返回 UploadFailed。响应正文会丢弃,不作为可信业务结果。
| 返回状态 | 下一步 |
|---|---|
| OK | 检查输出,调用 completeUploadPart,核对服务器分片结果;不能直接发布应用或触发签名。 |
| InvalidUploadTicket | 凭证类型、上传任务 ID / 序号、对象权限、白名单、大小摘要或有效期不符。停止并核对可信状态;需要新凭证时显式重新申请。 |
| IntegrityError / FileError | 本地内容、元数据或文件访问不符。核查源文件,不用变化后的内容覆盖原声明。 |
| TransportError / DeadlineExceeded / Cancelled | 远端可能已接收。保存上传任务 ID,恢复时先用原分片键确认,不能把超时视为必然未上传。 |
| UploadFailed / InvalidResponse | 文件传输被拒绝或响应异常。停止当前传输,核对网络并保留上传任务 ID 联系平台;不输出敏感响应或签名 URL。 |
| UnsupportedPlatform | 当前文件助手仅实现 Linux / POSIX;Windows 在文件 / 网络操作前返回此状态。其他环境矩阵仍须验收。 |
失败后如何继续
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| InvalidUploadTicket / IntegrityError | 凭证绑定、范围或实际内容不符。 | 核对原分片记录,不修改摘要覆盖原声明。 |
| 传输超时或取消 | 远端可能已经收到字节。 | 先用原确认键向平台核对,只有 PartMissing 才补传。 |
| UploadFailed / InvalidResponse | 传输被拒绝或响应异常。 | 停止本次传输,保留上传任务 ID 与安全错误信息联系平台。 |
文件助手使用 Linux / POSIX 文件接口。其他系统的支持范围见源码包 README,收到 UnsupportedPlatform 时应停止本次文件操作。网络中断后先核对原记录,不自动开始另一项业务。