2 媒资上传

媒资上传模块主要展示通过服务端API进行文件上传的API调用、回调和代码示例(含断点续传)。除服务端API调用上传外,也可通过登录控制台进行网页上传,或接入上传SDK进行上传。

2.1 媒资上传初始化

2.1.1 接口描述

域名:vcloud.163.com

接口名:/app/vod/upload/init

用于媒资上传的初始化,获取xNosToken(上传凭证)、bucket(存储对象的桶名)、object(生成的唯一对象名)。

2.1.2 输入参数

参数 类型 必须 说明
originFileName String 上传文件的原始名称(包含后缀名)
userFileName String 用户命名的上传文件名称
typeId Int 视频所属的类别Id(不填写为默认分类)
presetId Int 视频所需转码模板Id(不填写为默认模板,默认模板不进行转码)
uploadCallbackUrl String 上传成功后回调客户端的URL地址(需标准http格式)
callbackUrl String 转码成功后回调客户端的URL地址(需标准http格式)
description String 上传视频的描述信息
watermarkId Int 视频水印Id(不填写为不添加水印,如果选择,
请务必在水印管理中提前完成水印图片的上传和参数的配置;
且必需设置prestId字段,且presetId字段不为默认模板)
userDefInfo String 用户自定义信息,回调会返回此信息(长度不能超过256字符)
transOffset Int 视频转码处理裁剪视频的起始位置(单位:秒)
transDuration Int 视频转码处理裁剪视频的视频时长(单位:秒)

2.1.3 输出参数

参数 类型 说明
code Int 状态码
xNosToken String 上传凭证
bucket String 存储上传文件的桶名
object String 存储上传文件的对象名
msg String 错误信息

2.1.4 响应状态码

状态码 含义
200 操作成功
400 请求报文格式错误,报文构造不正确或者没有完整发送
700 服务器内部出现错误,请稍后重试或者将完整错误信息发送给客服人员帮忙解决
710 权限认证失败,请参考文档中的接口鉴权部分
720 访问失败,余额不足
721 服务未开通,请前往开通页面申请服务开通
722 服务开通审核中,请联系客服人员开通服务
723 请求的次数超过了配额限制

2.1.5 示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338bf05cc4a65b5d98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028a2a28b3628584e65a2abe7ae13" -d'{"originFileName":"love.mp4","userFileName":"for_love.mp4","typeId":20,"presetId":20,"description":"for love","wartermarkId":20}' https://vcloud.163.com/app/vod/upload/init

输出1

"Content-Type": "application/json; charset=utf-8"
{
    "code" : 200,
    "ret" : {
        "xNosToken" : "UPLOAD ab1856bb39044591939d7b94e1b8e5ee:n5VKrOLVFkLM7JIBDaCyPjzVKswqfxBZak2U2fXh0xM=:eyJCdWNrZXQiOiJ2b2RrMzJ5d3hkZiIsIk9iamVjdCI6ImEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEciLCJFeHBpcmVzIjoxNDY5NTg3NTc5LCJDYWxsYmFja1VybCI6Imh0dHA6Ly8xMDYuMi40NC4yNDgveGhyL3ZvZC9ub3MvY2FsbGJhY2siLCJDYWxsYmFja0JvZHkiOiJmaWxlTmFtZT10ZXN0LkpQRyZvYmplY3ROYW1lPWEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEcmJChPYmplY3RTaXplKSZ1aWQ9MjQxMzMmdHlwZUlkPTAmcHJlc2V0SWQ9MCZ3YXRlcm1hcmtJZHM9bnVsbCZkZXNjcmlwdGlvbj1udWxsJnZpZGVvQ2FsbGJhY2s9bnVsbCYkKEFWaW5mby5WaWRlby5EdXJhdGlvbikmJChBVmluZm8uVmlkZW8uSGVpZ2h0KSYkKEFWaW5mby5WaWRlby5XaWR0aCkmMCYwJjAmbnVsbCZ1cGxvYWRTdGFydD0xNDY2OTk1NTc5NjU4In0=",
        "bucket" : "vodk32ywxdf",
        "object" : "d37906a7-0119-4dd9-820d-4c66a71952ad.mp4"
    }
}

2.2 获取上传地址

2.2.1 接口描述

域名:http://wanproxy.127.net

接口名:/lbs?version=1.0&bucketname={bucket}

用于获取上传加速节点地址。

2.2.2 输入参数

参数 类型 必须 说明
version String API版本号,填写固定值1.0
bucketname String 存储上传文件的桶名,可在视频上传初始化接口的返回参数bucket获取

2.2.3 输出参数

参数 类型 说明
lbs String httpDNS的IP访问地址,用于避免后续查询的DNS解析时间、以及域名劫持
upload List 上传节点列表(前面的优先级高)

2.2.4 响应状态码

参数 类型 说明
Code String 错误代码
Message String 错误描述信息

2.2.5 示例代码

输入1

curl -X GET http://wanproxy.127.net/lbs?version=1.0&bucketname=vodk32ywxdf

输出1

{"lbs":"http://223.252.196.39/lbs","upload":["http://223.252.216.48","http://223.252.216.49"]}

2.3 媒资上传

上传一块数据,此接口通过指定offset实现断点续传功能。用户每次上传要以服务器端返回的offset为准续传余下数据。

需注意以下事项:

2.3.1 接口描述

POST {UploadHost}/{bucket}/{object}

重要提示:{UploadHost}值为获取的上传加速节点地址,{bucket}值为存储对象的桶名,{object}值为生成的唯一对象名。

2.3.2 输入参数

参数 类型 必须 说明
x-nos-token String 请求头参数,上传token
Content-Length long 请求头参数,当前片的内容长度,
单位:字节(Byte)。Content-Length合法值是[0~4M],
否则返回400 httpcode给客户端,拒绝本次请求
Content-Type String 请求头参数,标准http头。表示请求内容的类型,
比如:image/jpeg。 仅第一次上传生效,续传不生效
Content-MD5 String 请求头参数,文件内容md5值
bucket String 存储对象的桶名
object String 生成的唯一对象名
offset long 当前分片在整个对象中的起始偏移量,单位:字节(Byte)
complete String 是否为最后一块数据。合法值:true/false
version String http api版本号。这里是固定值1.0
context String 上传上下文。本字段是只能被上传服务器解读使用的不透明字段,
上传端不应修改其内容。
注意:用户第一次上传应不带此参数或置为空字符串,
之后上传剩余部分数据都需要带上这个参数。
context对应的桶名或者对象名不匹配返回400 code

2.3.3 输出参数

2.3.3.1 响应成功输出参数
参数 类型 必须 说明
requestId String uuid字符串,服务器端生成的唯一UUID
offset long 下一个上传片在上传块中的偏移。
注意:偏移从0开始,比如:用户上传0-128字节后,
服务器返回的offset为128,下一次上传offset值应置为128
context String 上传上下文
callbackRetMsg String 上传回调信息
2.3.3.2 响应失败输出参数
参数 类型 说明
requestId String uuid字符串,服务器端生成的唯一UUID
errMsg String 错误描述信息

2.3.4 响应状态码

状态码 含义
200 上传分片成功
400 请求报文格式错误,报文构造不正确或者没有完整发送
403 上传凭证无效。token过期服务器会返回此状态码,用户需要重新申请token
500 服务器内部出现错误,请稍后重试或者将完整错误信息发送给客服人员帮忙解决
520 回调失败

2.3.5 示例代码

输入1

curl -X POST -H "Content-Length: 4194304" -H "x-nos-token: UPLOAD ab1856bb39044591939d7b94e1b8e5ee:n5VKrOLVFkLM7JIBDaCyPjzVKswqfxBZak2U2fXh0xM=:eyJCdWNrZXQiOiJ2b2RrMzJ5d3hkZiIsIk9iamVjdCI6ImEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEciLCJFeHBpcmVzIjoxNDY5NTg3NTc5LCJDYWxsYmFja1VybCI6Imh0dHA6Ly8xMDYuMi40NC4yNDgveGhyL3ZvZC9ub3MvY2FsbGJhY2siLCJDYWxsYmFja0JvZHkiOiJmaWxlTmFtZT10ZXN0LkpQRyZvYmplY3ROYW1lPWEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEcmJChPYmplY3RTaXplKSZ1aWQ9MjQxMzMmdHlwZUlkPTAmcHJlc2V0SWQ9MCZ3YXRlcm1hcmtJZHM9bnVsbCZkZXNjcmlwdGlvbj1udWxsJnZpZGVvQ2FsbGJhY2s9bnVsbCYkKEFWaW5mby5WaWRlby5EdXJhdGlvbikmJChBVmluZm8uVmlkZW8uSGVpZ2h0KSYkKEFWaW5mby5WaWRlby5XaWR0aCkmMCYwJjAmbnVsbCZ1cGxvYWRTdGFydD0xNDY2OTk1NTc5NjU4In0=" -d'[本次上传视频文件二进制内容数据]' "http://223.252.216.49/vodk32ywxdf/d37906a7-0119-4dd9-820d-4c66a71952ad.mp4?offset=0&complete=false&version=1.0"

输出1

{
    "requestId":"be82c2a0dffc000000005770a189d831",
    "offset":4194304,
    "context":"f3e26818-83c3-5a21-6ee4-39ff47af21c7",
    "callbackRetMsg":""
}

2.4 查询长传断点

根据上传上下文查询对应分片上传当前续传的offset,上下文要与bucketName/objectName匹配,否则返回400状态码。(bucketName和objectName要进行URL编码,字符编码格式使用utf-8)。

2.4.1 接口描述

GET {UploadHost}/{bucket}/{object}?uploadContext

重要提示:{UploadHost}值为获取的上传加速节点地址,{bucket}值为存储对象的桶名,{object}值为生成的唯一对象名。

2.4.2 输入参数

参数 类型 必须 说明
x-nos-token String 上传token
bucketName String 存储对象的桶名
objectName String 生成的唯一对象名
context String 上传上下文。本字段是只能被上传服务器解读使用的不透明字段,
上传端不应修改其内容。对应context在服务端不存在则返回404。
context对应的桶名或者对象名不匹配返回400 code。
version String http api版本号。这里是固定值1.0

2.4.3 输出参数

2.4.3.1 响应成功输出参数
参数 类型 必须 说明
requestId String uuid字符串,服务器端生成的唯一UUID,用于记录日志排查问题使用
offset long 下一个上传片在上传块中的偏移
2.4.3.2 响应失败输出参数
参数 类型 说明
requestId String uuid字符串,服务器端生成的唯一UUID
errMsg String 错误描述信息

2.4.4 响应状态码

状态码 含义
200 上传分片成功
400 请求报文格式错误,报文构造不正确或者没有完整发送
403 上传凭证无效。token过期服务器会返回此错误码,用户需要重新申请token
500 服务器内部出现错误,请稍后重试或者将完整错误信息发送给客服人员帮忙解决
404 对应context上传不存在

2.4.5 示例代码

输入1

curl -X GET -H "x-nos-token: UPLOAD ab1856bb39044591939d7b94e1b8e5ee:n5VKrOLVFkLM7JIBDaCyPjzVKswqfxBZak2U2fXh0xM=:eyJCdWNrZXQiOiJ2b2RrMzJ5d3hkZiIsIk9iamVjdCI6ImEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEciLCJFeHBpcmVzIjoxNDY5NTg3NTc5LCJDYWxsYmFja1VybCI6Imh0dHA6Ly8xMDYuMi40NC4yNDgveGhyL3ZvZC9ub3MvY2FsbGJhY2siLCJDYWxsYmFja0JvZHkiOiJmaWxlTmFtZT10ZXN0LkpQRyZvYmplY3ROYW1lPWEzM2U1MmQ3LTUxZGMtNDZhNS1iMTFlLWFiNmMyMmJiOTk2ZC5KUEcmJChPYmplY3RTaXplKSZ1aWQ9MjQxMzMmdHlwZUlkPTAmcHJlc2V0SWQ9MCZ3YXRlcm1hcmtJZHM9bnVsbCZkZXNjcmlwdGlvbj1udWxsJnZpZGVvQ2FsbGJhY2s9bnVsbCYkKEFWaW5mby5WaWRlby5EdXJhdGlvbikmJChBVmluZm8uVmlkZW8uSGVpZ2h0KSYkKEFWaW5mby5WaWRlby5XaWR0aCkmMCYwJjAmbnVsbCZ1cGxvYWRTdGFydD0xNDY2OTk1NTc5NjU4In0=" "http://223.252.216.49/vodk32ywxdf/d37906a7-0119-4dd9-820d-4c66a71952ad.mp4?uploadContext&context=f3e26818-83c3-5a21-6ee4-39ff47af21c7&version=1.0"

输出1

{
    "requestId":"be82c2a0dffc000000005770a189d832",
    "offset":4194304
}

2.5 查询媒资Id

2.5.1 接口描述

域名:vcloud.163.com

接口名:/app/vod/video/query

用于视频或水印上传完成后查询主Id。

2.5.2 输入参数

参数 类型 必须 说明
objectNames List 上传文件的对象名列表

2.5.3 输出参数

参数 类型 说明
code Int 状态码
list List 对象名和视频Id对应的列表
list.vid Long 视频主Id
list.imgId Int 视频水印图片Id
list.objectName String 存储上传文件的对象名
msg String 错误信息

2.5.4 响应状态码

状态码 含义
200 操作成功
400 请求报文格式错误,报文构造不正确或者没有完整发送
700 服务器内部出现错误,请稍后重试或者将完整错误信息发送给客服人员帮忙解决
710 权限认证失败,请参考文档中的接口鉴权部分
720 访问失败,余额不足。
721 服务未开通,请前往开通页面申请服务开通
722 服务开通审核中,请联系客服人员开通服务
723 请求的次数超过了配额限制

2.5.5 示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338bf05cc4a65b5d98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028a2a28b3628584e65a2abe7ae13" -d'{"objectNames":["33cf71b1-86ac-4555-a071-d70db07b9685.mp4"]}' https://vcloud.163.com/app/vod/video/query

输出1

"Content-Type": "application/json; charset=utf-8"
{
    "code" : 200,
    "ret" : {
        list : [
            {
                "objectName" : "33cf71b1-86ac-4555-a071-d70db07b9685.mp4",
                "vid" : 1008
            }
        ]
    }
}

2.6 上传回调

媒资上传支持上传成功回调通知。回调设置及管理详细见第5节:回调管理。

回调内容示例

{"name":"snow.mp4","origAddr":"http://vodk32ywxdf.vod.126.net/vodk32ywxdf/b3d259f4-a7bc-4119-ae24-60e0eb09216e.mp4","type":"upload","vid":1022,"user_defined":"userId=123456"}。

注意:请以实际收到的body字段为准,以下仅为body字段示例。

参数 类型 说明
type String 回调类型,上传回调固定为“upload”
vid Long 视频文件标识
name String 视频文件名称(上传时指定视频名称)
origAddr String 视频的播放地址
warnning String 视频类型检测结果,比如视频类型和上传指定不一致,mp4和flv类型的视频不适合流媒体播放拖动等
user_defined String 用户自定义字段值(上传时设置的值)