上传安装包
本页内容
通过统一上传流程将 IPA 或 APK 保存为版本。优先使用 SDK 上传助手完成传输和确认,再查询校验结果;业务代码无需选择存储厂商。本指南也说明如何中断恢复。
了解上传流程
通过统一上传流程把 IPA 或 APK 保存为应用版本。您只需准备应用 ID、文件和幂等键,调用 SDK 上传助手;平台处理传输服务的选择,SDK 自动完成凭证申请、文件传输与确认,无需配置存储厂商或后台账号。
文件传完后,平台还会校验安装包。上传任务成功并返回版本 ID 后,才能继续签名或分发。下方也提供自行实现 HTTP 客户端时的调用顺序。
- 创建上传任务
- 申请凭证并传输
- 提交安装包校验
- 查询并取得版本
选择上传方式
推荐直接调用 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 方法、请求头及截止时间;凭证过期时可为原任务重新申请。
步骤二:传输安装包
整包上传
- 调用 获取整包上传凭证 申请凭证。
- 按返回的方法、地址和请求头发送整个文件。
- 确认存储服务已成功接收文件。
分片上传
- 按任务返回的分片大小切分原文件,为每片计算实际大小和摘要。
- 调用 申报分片摘要 申报该片,再调用 获取分片上传凭证 申请凭证。
- 传输该分片后调用 确认分片已上传 确认。
- 重复处理其余分片。中断后先调用 查询已申报的分片,只补传未确认的分片。
注意平台 AccessKey、Cookie 和平台 API 的 Authorization 请求头只用于调用平台,不要发送到存储地址。访问存储时只使用上传凭证指定的授权信息。
步骤三:提交校验并取得版本
- 整包传输成功或全部分片确认后,调用 提交安装包校验。
- 使用原上传任务 ID 调用 查询上传任务 查询状态。
- 等待
state=succeeded且取得version_id。该版本 ID 用于后续签名、查询和下载。
上传进度达到 100% 只表示文件传输结束,不能作为安装包已保存成功的依据。企业签名后续步骤见企业签名接入;普通分发见应用分发接入。
中断恢复与错误处理
| 遇到的情况 | 处理方式 |
|---|---|
| 创建任务的响应丢失 | 使用原应用、原请求内容和原幂等键重试,不为同一次上传更换幂等键。 |
| 上传凭证过期 | 为同一个上传任务或分片重新申请凭证,继续发送原文件。 |
| 分片传输中断 | 查询分片列表,核对序号与摘要,只补传尚未确认的分片。 |
| 提交校验后超时 | 先查询原上传任务;正在校验时继续等待,成功后使用已返回的版本。 |
| 本地文件已经改变 | 停止恢复旧任务。核对原文件,确需上传另一份文件时重新创建任务。 |
| 不再继续上传 | 对仍处于 uploading 状态的任务调用 取消未完成上传,并保存处理结果。 |
排查问题时保存 request_id、上传任务 ID 和错误码。错误码说明见接入排错。