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

C SDK:传输与确认单个分片

本页内容

自行调度上传时,发送一个已声明分片,并由业务 API 确认其保存结果。

适用场景

本页适用于已经自行调度分片、只想传输并确认其中一片的 C 项目。助手负责该片的传输校验,平台确认后才将它记为已完成。

如果您只需要上传完整 IPA 或 APK,优先使用 完整可恢复上传助手,由 SDK 处理分片顺序与恢复。调用方无需选择存储厂商。

前提条件

  • 准备自己的业务应用、已有上传任务 ID 和已声明的分片。按产品授予 enterprise:UploadVersions 或 distribution:UploadVersions。
  • 保存原文件、当前分片的偏移、大小和 SHA-256,以及本片确认操作的稳定幂等键。
  • 已配置允许访问的 HTTPS 文件传输域名,并按 C SDK 入门准备 Linux / POSIX 运行环境。

操作步骤

  1. 按上传任务返回的布局确定当前分片,调用 申报分片摘要 声明其真实内容。
  2. 先调用 确认分片已上传 核对是否已保存。只有 404 / PartMissing 才申请凭证并补传。
  3. 取得 获取分片上传凭证 后,将凭证与独立保存的本片参数交给 cloudsign_upload_part。
  4. 传输成功或提示对象已存在后,仍用原确认键调用 completeUploadPart,核对序号、大小、摘要和 uploaded。
  5. 所有分片均确认后,再提交整个安装包校验。单片确认不代表版本已经保存。

运行示例

配置网站主域名、长期 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 源码
C11 · 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_origins1–16 个独立配置的精确 HTTPS 源;不从凭证自动信任源,不使用通配符、IP 字面量、非 443 端口、路径或查询。DNS 与出口策略仍由接入方维护。
total_timeout_ms / cancelled / context总预算 1000–600000 ms,包含读取、摘要、回调和网络。同步回调须有界;本地文件系统与阻塞回调无法被强制中断,返回后仍检查预算。context 保持有效。
ca_file默认系统 CA,可从可信配置指定 CA 文件。证书、主机名与 TLS 1.2 最低版本验证始终开启。
cloudsign_uploaded_partsize_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 时应停止本次文件操作。网络中断后先核对原记录,不自动开始另一项业务。