Web 端上传 SDK

最近更新时间:2024-08-08 12:07:51

我的收藏
对于浏览器上传音视频的场景,云点播提供了 Web 上传 SDK。如果您需要 SDK 源码,可访问 SDK 源码

简单视频上传

引入 SDK

script 引入方式

未使用 webpack 的情况下,可通过 script 标签方式引入,该方式会暴露全局的 TcVod 变量。script 引入有下面两种方式:
下载到本地 下载 SDK 源码 到本地,然后按以下方式引入:
<script src="./vod-js-sdk-v6.js"></script>
说明:
引入路径请自行调整为您本地保存的路径。
使用 CDN 资源 使用 CDN 资源,可直接按以下方式引入:
<script src="https://cdn-go.cn/cdn/vod-js-sdk-v6/latest/vod-js-sdk-v6.js"></script>
单击此处 查看 script 方式引入的 Demo,请 单击此处 查看 Demo 源码。

npm 引入方式

使用 webpack 的情况下(如使用 Vue 或者 React),可通过 npm 引入:
// 安装稳定版本
// npm install vod-js-sdk-v6

import TcVod from 'vod-js-sdk-v6'
注意:
SDK 依赖 Promise,请在低版本浏览器中自行引入。

定义获取上传签名的函数

function getSignature() {
return axios.post(url).then(function (response) {
return response.data.signature;
})
};
说明:
url是您派发签名服务的 URL,更多相关信息请参见 客户端上传指引
signature计算规则请参见 客户端上传签名
应用视频文件分类任务流等信息都包含在上传签名中,更多相关信息请参见 签名参数说明

上传视频示例

// 通过 import 引入的话,new TcVod(opts) 即可
// new TcVod.default(opts) 是 script 引入 的用法
const tcVod = new TcVod.default({
getSignature: getSignature // 前文中所述的获取上传签名的函数
})

const uploader = tcVod.upload({
mediaFile: mediaFile, // 媒体文件(视频或音频或图片),类型为 File
})
uploader.on('media_progress', function(info) {
console.log(info.percent) // 进度
})

// 回调结果说明
// type doneResult = {
// fileId: string,
// video: {
// url: string
// },
// cover: {
// url: string
// }
// }
uploader.done().then(function (doneResult) {
// deal with doneResult
}).catch(function (err) {
// deal with error
})


说明:
new TcVod(opts) 中的 opts 指该接口的相关参数,详细请参见 TcVod 接口描述
上传方法根据用户文件的长度,自动选择普通上传以及分片上传,用户不用关心分片上传的每个步骤,即可实现分片上传。
如需上传至指定应用下,请参见 应用体系 - 客户端上传

高级功能

同时上传视频和封面

const uploader = tcVod.upload({
mediaFile: mediaFile,
coverFile: coverFile,
})

uploader.done().then(function (doneResult) {
// deal with doneResult
})

获取上传进度

SDK 支持以回调的形式展示当前的上传进度:
const uploader = tcVod.upload({
mediaFile: mediaFile,
coverFile: coverFile,
})
// 视频上传完成时
uploader.on('media_upload', function(info) {
uploaderInfo.isVideoUploadSuccess = true;
})
// 视频上传进度
uploader.on('media_progress', function(info) {
uploaderInfo.progress = info.percent;
})
// 封面上传完成时
uploader.on('cover_upload', function(info) {
uploaderInfo.isCoverUploadSuccess = true;
})
// 封面上传进度
uploader.on('cover_progress', function(info) {
uploaderInfo.coverProgress = info.percent;
})

uploader.done().then(function (doneResult) {
// deal with doneResult
})
xxx_uploadxxx_progress的回调值请参见 分块上传/复制任务操作

取消上传

SDK 支持取消正在上传的视频或封面:
const uploader = tcVod.upload({
mediaFile: mediaFile,
coverFile: coverFile,
})

uploader.cancel()

断点续传

SDK 支持自动断点续传功能,无需做额外操作。当上传意外终止时(如浏览器关闭、网络中断等),您再次上传该文件,可以从中断处继续上传,减少重复上传时间。

动态上传加速

1.7.0-beta.4 版本开始新增支持了通过 http2 协议上传,并根据网络状况动态调整上传并发的能力,有效提高上传速度,如需体验动态上传加速,需在控制台开启 全球链路加速
// 安装 beta 版本
// npm install vod-js-sdk-v6@1.7.0-beta.4

import TcVod from 'vod-js-sdk-v6'

const tcVod = new TcVod.default({
getSignature: getSignature // 前文中所述的获取上传签名的函数
})

const uploader = tcVod.upload({
mediaFile: mediaFile, // 媒体文件(视频或音频或图片),类型为 File
dynamicAccelerate: true, // 开启动态加速
})

接口描述

TcVod

参数名称
必填
类型
参数描述
getSignature
Function
获取上传签名的函数。
appId
number
填入后,内置的统计上报会自动带上。
reportId
number
填入后,内置的统计上报会自动带上。

TcVod.upload

参数名称
必填
类型
参数描述
mediaFile
File
媒体文件(视频或音频或图片)。
coverFile
File
封面文件。
mediaName
string
覆盖媒体文件元信息中的文件名。
fileId
string
当修改封面时传入。
enableResume
boolean
是否断点续传
enableRaceRegion
boolean
是否开启园区竞速,选择响应最快的园区发起上传,默认开启。
注:开启后会发起 HEAD 请求,这类请求会返回403状态码,不影响正式上传。
reportId
number
填入后,内置的统计上报会自动带上。会覆盖构造函数中的设置。
fileParallelLimit
number
同一个实例下上传的文件并发数,默认值3。
chunkParallelLimit
number
同一个上传文件的分块并发数,默认值6。
chunkRetryTimes
number
分块上传时,出错重试次数,默认值2(加第一次,请求共3次)。
chunkSize
number
分块上传时,每片的字节数大小,默认值8388608(8MB)。
progressInterval
number
上传进度的回调方法 onProgress 的回调频率,单位 ms ,默认值1000。
dynamicAccelerate
boolean
动态加速开关(1.7.0-beta.4版本新增)。

事件

事件名称
必填
事件描述
media_upload
媒体文件上传成功时。
cover_upload
封面上传成功时。
media_progress
媒体文件上传进度。
cover_progress
封面文件上传进度。

常见问题

1. File 对象怎么获取? 使用input标签,typefile类型,即可拿到File对象。
2. 上传的文件是否有大小限制? 最大支持60GB。
3. SDK 支持的浏览器版本有哪些? Chrome、Firefox 等支持 HTML5 的主流浏览器,IE 方面支持的最低版本是 IE10。
4. 如何实现类似暂停上传或恢复上传的功能? SDK 底层已经自动实现了断点续传的功能,因此暂停的本质即是调用uploader.cancel()这个方法。同理,暂停后的恢复上传也是调用初始的tcVod.upload方法,区别在于恢复上传时调用该方法的参数,应该是之前缓存起来的参数(例如可以在启动上传时全局变量存储一份参数,上传完成后再清掉)。
5. Web 端上传 SDK 是否支持使用 https: 域名上传? 可以支持。Web 端默认判断当前页面的域名是 http: 时,使用 http: 域名上传。若判断域名非 http: 时,则使用 https: 域名上传。

错误码列表

4XX 类型错误

HTTP 状态码
错误码
描述
400 Bad Request
ActionAccelerateNotSupported
加速域名不支持该操作
400 Bad Request
AttachmentFull
ACL 和 Policy 数量到达上限。详情请参见 规格与限制
400 Bad Request
BadDigest
提供的 Content-MD5 值与服务端收到的请求体的 MD5 哈希值不一致。
400 Bad Request
BadRequest
参数错误
400 Bad Request
BucketAccelerateNotEnabled
该存储桶未启用加速域名
400 Bad Request
BucketNameTooLong
存储桶名称过长。详情请参见 存储桶命名规范
400 Bad Request
BucketVersionNotOpen
存储桶未启用版本控制
400 Bad Request
DNSRecordVerifyFailed
DNS 记录验证失败,请添加 CNAME 或 TXT 记录。DNS 记录可能需要最多10分钟生效。
400 Bad Request
EntitySizeNotMatch
请求体大小与 Content-Length 请求头不符
400 Bad Request
EntityTooLarge
上传的对象大小超过规定的最大值。详情请参见 规格与限制
400 Bad Request
EntityTooSmall
上传的对象大小不足规定的最小值,常见于分块上传。详情请参见 规格与限制
400 Bad Request
ExpiredToken
临时密钥 Token 已过期
400 Bad Request
ImageResolutionExceed
图片分辨率超出限制或动图帧数过多
400 Bad Request
ImageTooLarge
图片超过限制大小
400 Bad Request
IncompleteBody
请求体大小小于 Content-Length 请求头
400 Bad Request
IncorrectNumberOfFilesInPostRequest
POST Object 请求每次只允许上传一个对象
400 Bad Request
InvalidArgument
请求参数不合法,请确认是否允许携带该请求参数。
400 Bad Request
InvalidBucketName
存储桶名称不合法。详情请参见存储桶 命名规范
400 Bad Request
InvalidDigest
给定的 Content-MD5 值不合法
400 Bad Request
InvalidImageFormat
图片格式不合法
400 Bad Request
InvalidImageSource
图片源不合法
400 Bad Request
InvalidLocationConstraint
指定的 location 不合法
400 Bad Request
InvalidObjectName
对象名称不合法。详情请参见 对象键
400 Bad Request
InvalidPart
分块缺失
400 Bad Request
InvalidPartOrder
分块的编号不连续
400 Bad Request
InvalidPicOperations
Pic-Operations 请求头不合法
400 Bad Request
InvalidPolicyDocument
POST Object 请求中的策略(Policy)不合法
400 Bad Request
InvalidRegionName
不合法的地域名。详情请参见 地域和访问域名
400 Bad Request
InvalidRequest
请求不合法
400 Bad Request
InvalidSHA1Digest
请求内容 SHA1 校验不合法
400 Bad Request
InvalidTag
存储桶标签不合法。详情请参见 存储桶标签概述
400 Bad Request
InvalidTargetBucketForLogging
用于存放日志的目标存储桶不合法,目标存储桶必须与当前存储桶在同一个地域。
400 Bad Request
InvalidUploadStatus
当启用版本控制时不能使用 JSON API 上传对象,请使用 XML API。
400 Bad Request
InvalidURI
URI 不合法
400 Bad Request
InventoryFull
清单任务数量已达到限制。清单任务上限1000条。
400 Bad Request
JsonAPINotSupportOnMAZBucket
JSON API 不支持操作多 AZ 存储桶,请使用 XML API。
400 Bad Request
KeyTooLong
对象键过长。详情请参见 对象键
400 Bad Request
KmsException
密钥管理服务异常
400 Bad Request
KmsKeyDisabled
提供的密钥已被禁用
400 Bad Request
KmsKeyNotExist
提供的密钥不存在
400 Bad Request
ListPartUploadIdIsEmpty
UploadId 为空
400 Bad Request
LoggingConfExists
日志配置已存在
400 Bad Request
LoggingPrefixInvalid
日志前缀参数不合法
400 Bad Request
MalformedPolicy
策略格式不合法
400 Bad Request
MalformedPOSTRequest
该 POST 请求的请求体内容不合法
400 Bad Request
MalformedXML
请求体的 XML 格式不符合 XML 语法
400 Bad Request
MAZOperationNotSupportOnOAZBucket
单可用区(单 AZ)存储桶不支持多可用区(多 AZ)操作。关于多 AZ 特性及使用限制的说明请参见 多 AZ 特性概述
400 Bad Request
MissingRequestBodyError
请求体缺失
400 Bad Request
MultiAZFeatureNotSupport
当前地域不支持多可用区
400 Bad Request
MultiBucketNotSupport
跨地域复制只能设置一个目的存储桶
400 Bad Request
NotifyRuleEventConflict
通知规则 Event 冲突
400 Bad Request
NotifyRulePrefixConflict
通知规则 Prefix 冲突
400 Bad Request
NotifyRuleSuffixConflict
通知规则 Suffix 冲突
400 Bad Request
NotSupportedStorageClass
指定的 存储类型 不支持
400 Bad Request
OAZOperationNotSupportOnMAZBucket
多可用区存储桶不支持单可用区操作。关于多 AZ 特性及使用限制的说明请参见 多 AZ 特性概述
400 Bad Request
PolicyFull
ACL 和 Policy 数量到达上限。详情请参见 规格与限制
400 Bad Request
PolicyVersionFull
Policy 版本数量到达上限
400 Bad Request
RequestTimeout
请求超时
400 Bad Request
SsecDecryptHeaderInvalid
源文件使用 SSE-C 加密,需要在请求头中提供相同的密钥。
400 Bad Request
SSEContentNotSupported
加密方式不支持
400 Bad Request
SSEHeaderNotAllowed
该操作不支持指定的服务端加密头部
400 Bad Request
TargetBucketNameInvalid
目标存储桶名称不合法。详情请参见存储桶 命名规范
400 Bad Request
TooManyBuckets
存储桶数目达到上限200
400 Bad Request
UnexpectedContent
请求不支持相关内容
400 Bad Request
UserCnameInvalid
用户指定的 CNAME 不存在或不合法
400 Bad Request
UserNetworkTooSlow
用户的网络速度过慢
400 Bad Request
VerifyAlgorithmNotSupported
校验算法不支持
400 Bad Request
WebsiteURLInvalid
自定义域名 URL 不合法
400 Bad Request
XMLSizeLimit
XML 长度超过限制
402 Payment Required
PaymentRequired
超出费用配额限制
403 Forbidden
AccessDenied
签名或者权限不正确,拒绝访问。请参考 请求签名ACL 概述
403 Forbidden
AccessForbidden
跨域资源共享(CORS)请求被拒绝,请检查请求方法或请求头部中的 Origin、Access-Control-Request-Method、Access-Control-Request-Headers 是否在配置的 CORS 白名单中。
403 Forbidden
InvalidAccessKeyId
SecretID 不存在
403 Forbidden
InvalidObjectState
对象存储类型与操作请求冲突
403 Forbidden
NoProcessAuthority
没有处理图片的权限
403 Forbidden
RequestTimeTooSkewed
本地时间与服务器时间相差过大,超过15分钟。
403 Forbidden
Request has expired
发起请求的时间超过了签名的有效时间,或者本地系统时间和所在时区的时间不一致。详情请参见 常见问题
403 Forbidden
SignatureDoesNotMatch
客户端计算的签名与 COS 服务端计算的签名不一致。请参阅 请求签名 文档并借助 COS 请求签名工具 检查自行实现的签名过程。
403 Forbidden
UserNotSourceBucketOwner
当前用户不是源存储桶的拥有者
403 Forbidden
UserNotTargetBucketOwner
当前用户不是目标存储桶的拥有者
404 Not Found
InventoryConfigurationNotFoundError
清单配置未找到
404 Not Found
NoBucketQuotaPolicy
存储桶配额策略不存在
404 Not Found
NoSuchBucket
指定的存储桶不存在
404 Not Found
NoSuchCopySource
复制对象源不存在
404 Not Found
NoSuchCORSConfiguration
指定的跨域资源共享配置不存在
404 Not Found
NoSuchEncryptionConfiguration
指定的存储桶加密配置不存在
404 Not Found
NoSuchJob
指定的批量处理任务不存在
404 Not Found
NoSuchKey
指定的对象键不存在。检查对象是否存在请使用 HEAD Object 接口。
404 Not Found
NoSuchLifecycleConfiguration
指定的生命周期配置不存在
404 Not Found
NoSuchObjectLockConfiguration
指定的对象锁定配置不存在
404 Not Found
NoSuchPolicyVersion
指定的策略版本不存在
404 Not Found
NoSuchTagSet
指定的标签集合不存在
404 Not Found
NoSuchUpload
分块上传时指定的 UploadId 不存在
404 Not Found
NoSuchVersion
指定版本不存在
404 Not Found
NoSuchWebsiteConfiguration
指定的静态网站配置不存在
404 Not Found
OriginConfigurationNotFoundError
回源配置未找到
404 Not Found
ReplicationConfigurationNotFoundError
跨地域复制配置未找到
405 Method Not Allowed
MethodNotAllowed
此资源不支持该 HTTP 方法
405 Method Not Allowed
RestoreNonArchiveObject
不允许对非归档对象进行回热(恢复)
405 Method Not Allowed
UploadIdNotSupported
指定的 UploadId 由 JSON API 生成,不能使用 XML API 操作。
409 Conflict
AppendPositionErr
Append 操作时,对象长度和 Position 不一致。
409 Conflict
BucketAlreadyExists
指定的存储桶已存在
409 Conflict
BucketAlreadyOwnedByYou
指定的存储桶已存在且由当前账户创建
409 Conflict
BucketLocked
存储桶已锁定,不能操作跨地域复制或生命周期。
409 Conflict
BucketNotEmpty
存储桶不为空
409 Conflict
DomainConfigConflict
域名配置冲突,请删除冲突的记录。
409 Conflict
InvalidBucketState
存储桶状态与操作请求冲突,例如版本控制管理与跨地域复制的冲突。
409 Conflict
InvalidLockedTime
对象锁定时间无效
409 Conflict
ObjectLocked
对象已锁定,不允许覆盖上传或删除该对象,也不允许通过复制修改该对象的元数据。
409 Conflict
InvalidObjectState
对象状态与操作请求冲突
409 Conflict
PathConflict
存在同名对象的毫秒级并发冲突
409 Conflict
QuotaConflict
配额冲突
409 Conflict
QuotaOperationConflict
该存储桶的状态不适用于该操作
409 Conflict
RecordAlreadyExist
DNS 记录冲突,请删除冲突的记录,或添加 CNAME/TXT 记录。
409 Conflict
RestoreAlreadyInProgress
该对象正在回热(恢复)中
409 Conflict
UploadConflict
同一个对象键频繁上传会导致冲突
409 ObjectNotAppendable
ObjectNotAppendable
指定的对象不能追加
411 Length Required
MissingContentLength
Content-Length 请求头部缺失
412 Precondition Failed
PreconditionFailed
前置条件不匹配
416 Requested Range Not Satisfiable
InvalidRange
请求的对象范围不合法
424
Failed Dependency
MirrorFailed
镜像源站返回403
451 Unavailable For Legal Reasons
DomainAuditFailed
域名未备案
451 Unavailable For Legal Reasons
UnavailableForLegalReasons
当前服务不可用,请检查账号是否欠费,若无欠费可通过 内容合规 查看是否存在违规内容。

5XX 类型错误

HTTP 状态码
错误码
描述
500 Internal Server Error
InternalError
服务端内部错误
500 Internal Server Error
KmsInternalException
查询密钥管理服务时发生服务端内部错误
501 Not Implemented
NotImplemented
请求尚未实现
503 Service Unavailable
KmsFreqControl
请降低使用密钥管理服务的请求的访问频率
503 Service Unavailable
ServiceUnavailable
服务暂不可用,请重试
503 Service Unavailable
SlowDown
访问带宽超过阈值,触发流控。报错信息:Connection refused due to traffic overload.
访问频率超过阈值,触发频控。报错信息:Message:Reduce your request rate.

申请上传: ApplyUpload

错误码
描述
FailedOperation
操作失败。
InternalError
内部错误。
InvalidParameter.ExpireTime
参数值错误:过期时间。
InvalidParameterValue.CoverType
参数值错误:封面类型。
InvalidParameterValue.ExpireTime
参数值错误:ExpireTime 格式错误。
InvalidParameterValue.MediaType
参数值错误:媒体类型。
InvalidParameterValue.SubAppId
参数值错误:子应用 ID。
UnauthorizedOperation
未授权操作。

确认上传:CommitUpload

错误码
描述
InternalError
内部错误。
InvalidParameterValue.SubAppId
参数值错误:子应用 ID。
InvalidParameterValue.VodSessionKey
参数值错误:点播会话。
ResourceNotFound
资源不存在。
UnauthorizedOperation
未授权操作。