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

上传安装包

本页内容

通过统一上传流程将 IPA 或 APK 保存为版本。优先使用 SDK 上传助手完成传输和确认,再查询校验结果;业务代码无需选择存储厂商。本指南也说明如何中断恢复。

了解上传流程

通过统一上传流程把 IPA 或 APK 保存为应用版本。您只需准备应用 ID、文件和幂等键,调用 SDK 上传助手;平台处理传输服务的选择,SDK 自动完成凭证申请、文件传输与确认,无需配置存储厂商或后台账号。

文件传完后,平台还会校验安装包。上传任务成功并返回版本 ID 后,才能继续签名或分发。下方也提供自行实现 HTTP 客户端时的调用顺序。

  1. 创建上传任务
  2. 申请凭证并传输
  3. 提交安装包校验
  4. 查询并取得版本

选择上传方式

推荐直接调用 SDK 上传助手,提交应用 ID、文件和本次操作的幂等键即可。平台自动选择文件传输服务,SDK 自动申请上传凭证、切分文件并确认结果;业务代码无需判断存储厂商或填写后台存储配置。

上传助手使用通用分片流程,小文件只传一片,大文件按接口返回的大小分片。需要自行实现 HTTP 客户端时,按下表选择传输方式。

上传方式适用场景处理方式
分片上传(推荐)首次接入、小文件、大文件和断点续传。创建分片上传任务,按返回指令传输并确认。SDK 上传助手会自动完成这些步骤。
整包上传(可选)已有整包上传集成,且当前接口支持此方式。申请整包上传凭证并发送整个文件。若返回 StorageUnsupported,改用通用分片流程,无需识别底层存储。

一个上传任务对应一个安装包。可上传的大小以账号限额和接口返回值为准。创建成功后立即保存上传任务 ID,即响应中的 data.id。中断后保留原文件和幂等键,继续处理同一个上传任务。

开始前

  • 在开发者中心创建 API 应用和 AccessKey。企业签名需要 enterprise:UploadVersions,普通分发需要 distribution:UploadVersions,并限定到自己的目标应用。首次接入请先完成快速开始。
  • 准备应用 ID。已有应用从 列出已授权应用 取得;新应用先调用 预留新应用 创建应用预留。
  • 准备实际文件及其大小。企业签名使用 IPA;普通分发使用 IPA 或 APK,包名和平台应与目标应用一致。
  • 为每次写操作生成并保存幂等键。幂等键用于标记一次操作,网络重试时沿用原值,防止重复创建上传任务。

安装 SDK 后,可以使用其上传助手处理文件校验、分片和恢复。若自行实现 HTTP 调用,请按下面的步骤逐项处理。语言与运行准备见SDK 使用说明。

步骤一:创建并保存上传任务

调用 创建上传任务,填写应用、文件信息和上传方式。请求成功后,立即保存 data.id,它就是完整上传任务 ID(U…),并保存应用 ID、文件信息和幂等键,再开始传输文件。SDK 的保存回调对应这一步,详见上传助手。

上传任务 ID 用来查询进度、申请凭证、确认分片和提交校验。上传凭证则是一组短期访问授权,包含存储地址、HTTP 方法、请求头及截止时间;凭证过期时可为原任务重新申请。

步骤二:传输安装包

整包上传

  1. 调用 获取整包上传凭证 申请凭证。
  2. 按返回的方法、地址和请求头发送整个文件。
  3. 确认存储服务已成功接收文件。

分片上传

  1. 按任务返回的分片大小切分原文件,为每片计算实际大小和摘要。
  2. 调用 申报分片摘要 申报该片,再调用 获取分片上传凭证 申请凭证。
  3. 传输该分片后调用 确认分片已上传 确认。
  4. 重复处理其余分片。中断后先调用 查询已申报的分片,只补传未确认的分片。

注意平台 AccessKey、Cookie 和平台 API 的 Authorization 请求头只用于调用平台,不要发送到存储地址。访问存储时只使用上传凭证指定的授权信息。

步骤三:提交校验并取得版本

  1. 整包传输成功或全部分片确认后,调用 提交安装包校验。
  2. 使用原上传任务 ID 调用 查询上传任务 查询状态。
  3. 等待 state=succeeded 且取得 version_id。该版本 ID 用于后续签名、查询和下载。

上传进度达到 100% 只表示文件传输结束,不能作为安装包已保存成功的依据。企业签名后续步骤见企业签名接入;普通分发见应用分发接入。

中断恢复与错误处理

遇到的情况处理方式
创建任务的响应丢失使用原应用、原请求内容和原幂等键重试,不为同一次上传更换幂等键。
上传凭证过期为同一个上传任务或分片重新申请凭证,继续发送原文件。
分片传输中断查询分片列表,核对序号与摘要,只补传尚未确认的分片。
提交校验后超时先查询原上传任务;正在校验时继续等待,成功后使用已返回的版本。
本地文件已经改变停止恢复旧任务。核对原文件,确需上传另一份文件时重新创建任务。
不再继续上传对仍处于 uploading 状态的任务调用 取消未完成上传,并保存处理结果。

排查问题时保存 request_id、上传任务 ID 和错误码。错误码说明见接入排错。