veImageX 上传最佳实践
最近更新时间：2024.02.01 14:05:03
首次发布时间：2023.04.24 14:11:06
veImageX 上传，指将资源上传至 veImageX 服务存储中并使用 veImageX 进行丰富图片处理和分发。本文档将为您介绍 veImageX 的文件上传优势、上传方式等内容，以及介绍了如何更快存储文件和保证资源在各种复杂网络下能够成功放至存储空间中。
上传优势
加速
上传加速：上传流程分很多个请求，veImageX 把请求分为两类：OpenAPI 接口，数据传输接口。已主要针对数据传输接口完成上传优化，其耗时占整个上传流程的 80% 以上；
优化链路：利用 CDN 边缘覆盖和路由的优势，加速用户请求到源站的速度；
专线加速：利用已有机房的专线，加速用户请求到源站的速度。优化链路，同时解决部分国内外区域高失败率问题；
边缘就近存储：在某些场景下，利用搭建在全球的多个边缘存储节点，缩短物理距离，将用户上传的数据存储在最近的节点。
指标监控
用户视角监控：上传成功率、耗时等指标在控制台提供可视监控；
网络指标监控：网络质量、成功率等指标均提供了多种维度拆分与指标监控能力。
端策略优化
调度优化：支持多种调度算法，如长记忆调度、端调度、智能竞速等调度策略；
网络策略：支持断线重连、链路复用等网络策略；
协议优化：HTTP2/QUiC（未全部开放）等协议优化能力。
上传方式
资源类型限制：为了更好地区分、管理和排查问题，veImageX 对服务分为以下两种逻辑类型：
素材托管类型：不限制文件类型，任何类型均可以托管与上传；
图像处理类型：不限制文件类型，但可以更友好的支持分发处理图像文件（包括图片和小视频），具有更强的处理特性。
说明
两种服务类型均不限制上传文件类型，仅对于上传操作来讲，两种类型没有区别。
| 上传方式 | 适用场景 | 使用说明 | 推荐 |
|---|---|---|---|
| 控制台上传 | 快速、便捷地将少量本地资源上传到 veImageX 的场景 | 选择一个状态正常的服务，登录控制台参考上传文件完成上传 | - |
| 上传 SDK（服务端） | 自动化上传、大批量资源上传等场景 | 服务端上传 | 推荐 |
| 上传 SDK（客户端） | UGC、PGC 等场景 | 客户端上传 | 推荐 |
| URL 拉取上传 | 文件没有存储在本地服务器或终端，需要通过公网访问的 URL 地址上传的场景 | 调用 FetchImageUrl接口，该接口支持同步和异步的资源抓取 | 推荐 |
| 客户端同步工具 | 适合将本地的资源批量进行同步到 veImageX 的工具，本质是对上传 SDK 的一种封装使用 | 本地迁移与上传工具 | 推荐 |
| 三方云存储迁移 | 文件存在于阿里云、腾讯云等其他三方云存储的场景 | 数据迁移 | - |
服务端上传
上传前准备：请参考开发准备提前获取 AK 和 SK, 并完成创建 veImageX 服务获取 ServiceID。
适用场景：待上传的数据存在于业务服务器侧、或者数据已经在服务器侧需要将数据做迁移。
若待迁移数据源于终端用户，推荐使用下述客户端上传方式接入，可以有效利用上传加速服务，强烈不建议业务前端或 App 端将文件数据传给业务服务端，然后再由业务服务端上传至 veImageX。原因是在整个上传过程中用户首先将数据上传到“业务服务端”再上传到 veImageX，“业务服务端”很容易成为整个上传链路的瓶颈，也使得上传加速效果大打折扣。
上传流程
服务端上传时序图如下图所示，整体分为三步：
业务服务端发起 ApplyImageUpload请求，请求获取文件上传和上传凭证。
业务服务端使用公网域名上传文件二进制数据。通过对步骤 1 Apply 返回的上传地址发起 PUT 请求上传文件，因使用的公网域名，对上传机房无限制，推荐仅在测试时使用。线上的业务服务采用此方式上传将对性能产生较大影响。
业务服务端发起 CommitImageUpload上传结果确认请求，veImageX 上报上传完成。
说明
强烈不建议依赖此步骤返回的图片 meta 信息，有获取 meta 需求推荐在上传完成后拼接
~info模板获取图片 meta 信息。原因请见为什么不建议依赖 Commit 阶段返回的图片 meta 信息？若无控制台资源列表查看文件的需求，可跳过该阶段来优化整体上传延迟。跳过后资源列表默认不展示上传的文件，但您可在控制台直接搜索文件名。
上传接入
veImageX 已提供 Golang/Python/JAVA/PHP/Nodejs 共五种语言版本的 SDK 供业务服务端接入，服务端 SDK 中封装了上述流程中的各个步骤，业务服务端只需调用 SDK 即可完成资源上传。
注意
- 建议您在设置上传参数时，可以通过传递
StoreKeys来达到指定文件名的效果。文件存储 URI：Tos-i-xxxx/StoreKey.文件后缀，您可直接使用精简方式访问源地址http://域名/StoreKey.文件后缀。 - 对于如上暂未提到的其他语言的业务服务，veImageX 暂无 SDK 支持，建议业务根据上述上传流程自行调用 OpenAPI 实现，OpenAPI 的鉴权逻辑可参考 API 调用必看说明 。
客户端上传
适用场景：终端用户资源上传一般是 UGC 上传场景。
上传加速：根据终端用户所在的物理位置、使用的运营商等信息，同时结合视频架构各个机房的资源健康状况，为用户分配一个最优的上传线路动态下发，可以有效提升区域用户的上传速度，同时可以快速支持机房容灾切换。
上传流程
业务 App/Web 端向业务服务端发起获取上传签名请求。
说明
上传 OpenAPI 包含鉴权机制，签名生成需要 AK/SK，而 AK/SK 等敏感信息放在端上容易造成泄露，同时业务的 AK/SK 信息 veImageX 也无权限获取，因此需要业务服务端开发封装获取签名接口，具体参考下文客户端上传接入。
业务服务端需要对该接口请求的用户身份进行校验，避免恶意用户获取签名后任意上传。
业务 App/Web 端向 veImageX 发起 ApplyImageUpload请求获取上传参数。
业务 App/Web 端对 Apply 返回的上传地址发起 PUT 请求，上传文件二进制数据。
业务 App/Web 端发起 CommitImageUpload上传结果确认请求，veImageX 上报上传完成。
说明
强烈不建议依赖此步骤返回的图片 meta 信息，有获取 meta 需求推荐在上传完成后拼接~info模板获取图片 meta 信息。原因请见为什么不建议依赖 Commit 阶段返回的图片 meta 信息？
上传完毕后，将结果上报存入数据库。
上传接入
Step 1：获取上传凭证
业务服务端可以接入 veImageX SDK 来生成上传凭证，然后下发给客户端。
Step 2：文件上传
veImageX 已提供 Android、iOS 双端和 Web 端的资源上传 SDK 供业务 App 端、Web 端接入，具体请参考：
上传相关域名
上传过程中会涉及到以下两类域名：
OpenAPI 域名：即请求上传 OpenAPI（包括 Apply 和 Commit）用到的域名。veImageX 提供的 OpenAPI 域名列表如下：
Region 英文缩写 OpenAPI 域名 中国 cn-north-1 https://imagex.volcengineapi.com 新加坡 ap-singapore-1 https://imagex-ap-singapore-1.volcengineapi.com 上传域名：即上传数据时使用的域名，上传域名一般为 Apply 阶段动态下发的，业务无需关注。
常见问题
可以上传非图片文件吗？
SDK 上传：可以。上传非图片文件时上传过程不会报错，同时图像处理服务分发非图片文件时将统一作为二进制文件分发。
为什么不建议依赖 Commit 阶段返回的图片 meta 信息？
上传 Commit 阶段会带来额外的延迟开销和失败风险，尤其是在批量上传的场景。veImageX 认为资源上传的优先级更高，因此在获取 meta 超时或失败的时候，上传流程仍会返回成功，但相关的 meta 信息字段会返回空。
建议业务不要强依赖此处的 meta 返回值，您可选择通过~info模板来获取图片 meta 信息。
如何确定图片的上传结果？
请关注 Commit 阶段返回的UriStatus字段，2000 表示上传成功，2001 表示上传失败。
有哪些手段可以优化上传延迟？
对于客户端上传 SDK，如无需在上报阶段使 SDK 返回图片 Meta 信息，建议跳过图片 Meta 信息上报。
对于客户端上传 SDK，如无需在控制台列表查看文件需求，可指定跳过上传成功后的 Commit 上报阶段。
多个资源上传场景，建议使用批量上传，以减少 OpenAPI 请求带来的延迟影响。