文档中心 > 多媒体服务

REST API

更新时间：2016/01/27 访问次数：88481

1、约定
2、上传
3、管理
4、附录

1、约定

1.本API在设计时，尽量使用了HTTP原语 GET、PUT、POST、DELETE 表示操作动作；

2.用户的Token生成请务必放在服务端进行，严防SK泄露；

3.上传文件使用MultiPart的方式，每个上传参数都作为单独的Part出现；

4.文件一定作为最后一个Part，否则文件之后的Part部分将丢失；

5.Token的过期时间由用户通过时间戳指定，如果401错误频发，请确保服务器时间与图片服务的时间同步。

2、上传

2.1 上传策略

上传策略是提供给开发者用于控制上传相关行为与限制的一个配置设定。为了防止传输过程中对上传策略进行篡改，上传策略将作为签名字段包含在Authorizaton HTTP Header中。（详见上传凭证一节）
编码前的上传策略是JSON格式的，示例如下：

JSON格式

{
    "callbackBody":     "<string>",
    "callbackBodyType": "<string>",
    "callbackHost":     "<string>",
    "callbackUrl":      "<string>",
    "detectMime":       "<int>",
    "dir":              "<string>",
    "expiration":       "<long>",
    "insertOnly":       "<int>",
    "mimeLimit":        "<string>",
    "name":             "<string>",
    "namespace":        "<string>",
    "returnBody":       "<string>",
    "returnUrl":        "<string>",
    "sizeLimit":        "<long>"
    "mediaEncode":      "<mediaEncodePolicy>"
}

各上传策略的字段描述详见下表：

字段名称	是否必须	说明
dir	否	指定上传文件的存储路径如果不指定则会使用接口中传入的dir参数如果接口中也没有传入dir参数,则默认使用根目录该参数可以包含占位符例如： uploadPolicy.setDir("/${year}/${month}/${day}");
name	否	指定上传文件的存储文件名如果不指定则会使用接口中传入的name参数如果接口中也没有传入name参数,将会抛出异常该参数可以包含占位符例如： uploadPolicy.setName("${hour}-${minute}-${second}.${ext}");
sizeLimit	否	指定上传文件大小的最大值(单位:字节) 各种资源类型文件大小的系统限制图片: 10485760 (10Mb: 10 * 1024 * 1024) 默认情况下使用系统限制检查文件大小
mimeLimit	否	指定上传文件类型的限制(MimeType类型) 允许指定多种类型, 请使用';'隔开各种资源类型允许上传的MimeType类型图片: jpg: image/jpeg png: image/png bmp: image/bmp gif: image/gif 通配符: image/*
callbackUrl	否	图片上传完成之后,系统回调该Url
callbackHost	否	在系统回调时,将设置请求头部的Host信息设置该参数之前应该首先设置callbackUrl
callbackBody	否	在系统回调时,将设置请求的Body信息设置该参数之前应该首先设置callbackUrl 该参数可以包含占位符
callbackBodyType	否	在系统回调时,将设置请求的Body类型设置该参数之前应该首先设置callbackUrl 设置该参数之前应该首先设置callbackBody
insertOnly	是	文件上传是否可覆盖 0: 可覆盖, 1: 不可覆盖默认为可覆盖的模式
detectMime	否	是否自动检查文件头部信息 0: 不自动检查, 1: 自动检查默认为自动检查文件头部信息
returnUrl	否	上传完成之后,303跳转的Url
returnBody	否	上传完成之后,返回的Body信息该参数可以包含占位符
namespace	是	开发者创建空间时指定的空间唯一标示
expiration	是	token的过期时间，-1为永不过期举例如下: (System.currentTimeMillis() + 3600 * 1000)表示该Token一小时后失效
mediaEncode	否	视频转码策略配置具体见附录：上传策略-视频转码参数表 MediaEncodePolicy

一个包含视频转码上传策略例子:

{
    "detectMime": 1,
    "expiration": -1,
    "insertOnly": 0,
    "mediaEncode": {
        "notifyUrl": "http://sample.com/notify",
        "tasks": [
            {
                "encodeTemplate": "video-generic-AVC-1080P",
                "force": "true",
                "output": {
                    "dir": "/video",
                    "name": "output.mp4",
                    "namespace": "imagedemo"
                },
                "watermark": {
                    "dir": "/wartermark",
                    "name": "test.png",
                    "namespace": "imagedemo"
                },
                "watermarkTemplate": "myWatermark",
                "usePreset": "true",
                "seek": "1",
                "duration": "10"
            }
        ]
    },
    "namespace": "service",
    "sizeLimit": 0
}

2.2 占位符

上传策略中有些策略（例如dir、callbackBody等可以包含类似系统时间、图片长宽、用户自定义变量等），在开发者编写上传策略的时候并不知道具体值，这时，可以通过占位符(${占位符名称})进行表示，由顽兔多媒体服务在运行时进行渲染填充。

例如: 可以在上传策略中指定文件名为 ${year}-${month}-${day}.jpg , 运行时生成的文件名可能就会是这样 2015-2-5.jpg

目前支持的占位符如下列表：

占位符名	说明
namespace	开发者创建空间时指定的空间唯一标示
dir	文件路径(不可以用来渲染dir和name)
name	文件名(不可以用来渲染dir和name)
mimeType	文件类型(MimeType) (中间有'/', 请不要用于渲染name)
mediaType	文件MIME前缀, 多媒体文件类型(取自MimeType)
ext	文件MIME后缀, 文件扩展名(取自MimeType)
year	上传时间的年份
month	上传时间的月份
day	上传时间的日期
hour	上传时间的小时(24小时制)
minute	上传时间的分
second	上传时间的秒
fileSize	上传文件的大小
uuid	生成uuid
width	图片宽
height	图片高
exif	图片的Exif信息，里面包含了诸多子项可以通过exif.xxx来获取
自定义占位符 var-*	用户自定义占位符("var-"为参数前缀, "*"为用户用于渲染的自定义占位符名)，包含在上传参数中
自定义元信息 meta-*	用户自定义的文件meta信息("meta-"为参数前缀, "*"为用户用于渲染的自定义Meta信息名) ，包含在上传参数中

注意:
非系统占位符或非自定义占位符，不能使用${}符号，否则会导致占位符渲染失败；
当发生重名时, 会以该顺序进行选择: 系统占位符、用户自定义文件meta占位符、用户自定义占位符。在上传的时候, 如果需要指定一个名称为cat的占位符, 需要使用名称为var-cat的参数声明该自定义占位符；meta则对应meta-cat。

2.3 上传凭证

上传凭证是顽兔多媒体服务用于验证上传请求合法性的机制。用户通过上传凭证授权客户端，使其具备访问指定资源的能力。

计算方法

1.构造上传策略

开发者根据业务需求，确定上传要素，并据此构造上传策略。

比如，有用户需要向空间my-space上传一个图片，授权有效期截止到2015-12-31 00:00:00，并且希望得到图片的目录、名称、大小、宽高。那么相应的上传策略各字段分别为：

namespace = 'myspace'
expiration = 1451491200000
returnBody = '{
    "dir": ${dir},
    "name": ${name},
    "size": ${filesize},
    "w": ${width},
    "h": ${height},
}'

2.将上传策略格式化为JSON格式

用户可以使用各种语言的JSON库，也可以手工地拼接字符串。

序列化后，应得到如下形式的字符串（字符串值以外部分不含空格或换行）。

uploadPolicy='{"namespace":"myspace","expiration":1451491200000,"returnBody":"{\"dir\":${dir},\"name\":${name},\"size\":${filesize},\"w\":${width},\"h\":${height} }"}'

3.对JSON编码的上传策略进行URL安全的Base64编码（详情参见RFC4648 ）

encodedPolicy = urlsafe_base64_encode(uploadPolicy)

得到待签名字符串：

eyJkZXRlY3RNaW1lIjoxLCJleHBpcmF0aW9uIjotMSwiaW5zZXJ0T25seSI6MSwibmFtZXNwYWNlIjoibmFtZXNwYWNlIiwic2l6ZUxpbWl0IjowfQ

4.使用SK对编码后的上传策略计算HMAC-SHA1签名

sign = hex(hmac_sha1(encodedPolicy, "<SecretKey>"))

使用hmac_sha1算法得出的byte数组结果需要转换成十六进制hex字符串，字符串的字母“全为小写”
得到：

184eeb1d1673b761dc87ab7eb3dba7e2890cf016

5.将AK、encodedPolicy和sign用“ ：”连接起来，再一次进行URL安全的Base64编码，并加上前缀 “UPLOAD_AK_TOP”

uploadToken = UPLOAD_AK_TOP  url_safe_base64(AccessKey + ':' + encodedPolicy + ':' + sign)

即是最后的上传凭证。

测试工具： 点击查看

6.上传凭证需要在文件上传时包含在HTTP的Authorization 头中，示例为：

Authorization : UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

2.4 公共请求头

目前，公共请求头只包含Authorization一个字段，用于对上传请求进行鉴权验证。参数格式如下：

Authorization : type base64(accessKey:base64(uploadPolicy):signature)

说明：

type: 用户验证类型 (当前使用 UPLOAD_AK_TOP)

uploadPolicy: 用户的上传策略

signature: hmac_sha1(base64(uploadPolicy), accessKeySecret)

base64: URLSafe Base64 编码

hmac_sha1: 哈希运算消息认证码（Hash-based Message Authentication Code）, 加密用散列函数（SHA-1）

详情请参见上传策略一节，Java开发者可直接阅读SDK源码。

2.5 上传服务器地址

上传服务器域名：

http://upload.media.aliyun.com

2.6 普通上传

请求Url: /api/proxy/upload

请求头部: 参考公共请求头部

请求参数

参数	说明	必须	参数位置
dir	文件目录		Body
name	文件名	(上传策略中的name不存在，则必传)	Body
meta-*	用户自定义的文件meta信息("meta-"为参数前缀, "*"为用户用于渲染的自定义Meta信息名)		Body
var-*	用户自定义的魔法变量("var-"为参数前缀, "*"为用户用于渲染的自定义魔法变量名)		Body
md5	文件md5值	否(推荐提供此参数进行一致性检查)	Body
content	文件内容	是(必须位于参数的最后一位)	Body
size	文件大小	是	Body

返回参数

参数	说明
dir	文件目录
name	文件名
returnBody	返回开发者自定义的内容，会被魔法变量渲染
customBody	返回回调开发者服务的响应内容
url	用户上传完成图片的url
eTag	目标资源的hash值，可用于http eTag头部

请求示例

请求头

POST /api/proxy/upload HTTP/1.1
Host: upload.media.aliyun.com
Content-Length: 81582
Content-Type: multipart/form-data; boundary=zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq
Accept-Encoding: gzip,deflate
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.6 (java 1.5)
Authorization: UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

请求体

--zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq
Content-Disposition: form-data; name="md5"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

43f8c8bef85309bdd1863977bc48736a
--zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq
Content-Disposition: form-data; name="size"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

80690
--zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq
Content-Disposition: form-data; name="dir"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/dir
--zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq
Content-Disposition: form-data; name="name"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

name
--zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq
Content-Disposition: form-data; name="content"; filename="jpgTest.jpg"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

[80690 bytes of object data]
--zcV4qZ1R8f7jaG7hzVlZ_RL9oOdIZWv9tUCoKq--

返回示例

HTTP/1.1 200 OK
fileSize: 80690
dir: /dir
requestId: 0bab1b37-d12d-48ba-a794-d672217bdc59
name: name
fileModified: 1423465476942
url: http://default-60011620.img.cdn.aliapp-inc.com/dir/name
mimeType: image/jpeg

2.7 初始化分片上传

请求Url: /api/proxy/blockInit

请求头部: 参考公共请求头部

请求参数

参数	说明	必须	参数位置
dir	文件目录		Body
name	文件名	(上传策略中的name不存在，则必传)	Body
meta-*	用户自定义的文件meta信息("meta-"为参数前缀, "*"为用户用于渲染的自定义Meta信息名)		Body
var-*	用户自定义的魔法变量("var-"为参数前缀, "*"为用户用于渲染的自定义魔法变量名)		Body
md5	文件md5值	否(推荐提供此参数进行一致性检查)	Body
content	文件内容	是(必须位于参数的最后一位)	Body
size	文件大小	是	Body

返回参数

参数	说明
partNumber	块编号
id	上传唯一id
uploadId	分片上传Id
eTag	目标资源的hash值，可用于http eTag头部

请求示例

请求头

POST /api/proxy/blockInit HTTP/1.1
Host: upload.media.aliyun.com
Content-Length: 205381
Content-Type: multipart/form-data; boundary=Cie-vMEXlifXjJxRjzQxsMiPBRuRXJG0uRnjPW-v
Accept-Encoding: gzip,deflate
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.6 (java 1.5)
Authorization: UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

请求体

--Cie-vMEXlifXjJxRjzQxsMiPBRuRXJG0uRnjPW-v
Content-Disposition: form-data; name="size"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

204800
--Cie-vMEXlifXjJxRjzQxsMiPBRuRXJG0uRnjPW-v
Content-Disposition: form-data; name="name"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

name
--Cie-vMEXlifXjJxRjzQxsMiPBRuRXJG0uRnjPW-v
Content-Disposition: form-data; name="content"; filename="content"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

[204800 bytes of object data]
--Cie-vMEXlifXjJxRjzQxsMiPBRuRXJG0uRnjPW-v--

返回示例

HTTP/1.1 200 OK
id: 227435f9-0704-4fba-899c-8504b321f3d2
eTag: C97218D1B03053644B61644E286A67B8
uploadId: F2F7A3150F13414C875BD2B4AE8EB459
dir: /
requestId: 6273f936-d368-4420-b9d3-fab0c8f9fe58
name: name
partNumber: 1

2.8 分片上传

请求Url: /api/proxy/blockUpload

请求头部: 参考公共请求头部

请求参数

参数	说明	必须	参数位置
md5	文件md5值	否(推荐提供此参数进行一致性检查)	Body
id	上传唯一id	是	Body
uploadId	分片上传Id	是	Body
partNumber	块编号	是	Body
content	分片内容	是(必须位于参数的最后一位)	Body
size	分片大小	是	Body

返回参数

参数	说明
partNumber	块编号
eTag	目标资源的hash值，可用于http eTag头部

请求示例

请求头

POST /api/proxy/blockUpload HTTP/1.1
Host: upload.media.aliyun.com
Content-Length: 205728
Content-Type: multipart/form-data; boundary=nSxOQyz6shyhz-dJNOay_D8O4TsPSr
Accept-Encoding: gzip,deflate
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.6 (java 1.5)
Authorization: UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

请求体

--nSxOQyz6shyhz-dJNOay_D8O4TsPSr
Content-Disposition: form-data; name="size"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

204800
--nSxOQyz6shyhz-dJNOay_D8O4TsPSr
Content-Disposition: form-data; name="id"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

227435f9-0704-4fba-899c-8504b321f3d2
--nSxOQyz6shyhz-dJNOay_D8O4TsPSr
Content-Disposition: form-data; name="uploadId"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

F2F7A3150F13414C875BD2B4AE8EB459
--nSxOQyz6shyhz-dJNOay_D8O4TsPSr
Content-Disposition: form-data; name="partNumber"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

2
--nSxOQyz6shyhz-dJNOay_D8O4TsPSr
Content-Disposition: form-data; name="content"; filename="content"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

[204800 bytes of object data]
--nSxOQyz6shyhz-dJNOay_D8O4TsPSr--

返回示例

HTTP/1.1 200 OK
id: 227435f9-0704-4fba-899c-8504b321f3d2
eTag: F688008705725E1BB841BA1F7EAE0748
uploadId: F2F7A3150F13414C875BD2B4AE8EB459
dir: /
requestId: bd582558-e401-4f33-b733-f4cd496d32e7
name: name
partNumber: 2

2.9 分片上传完成

请求Url: /api/proxy/blockComplete

请求头部: 参考公共请求头部

请求参数

参数	说明	必须	参数位置
md5	文件md5值	否	Body
id	上传唯一id	是	Body
uploadId	分片上传Id	是	Body
parts	每个分片的md5值，格式json，需要进行base64的编码	是	Body

返回参数

参数	说明
dir	文件目录
name	文件名
returnBody	返回开发者自定义的内容，占位符会被渲染
customBody	返回回调开发者服务的响应内容
url	用户上传完成图片的url
id	上传唯一id
uploadId	分片上传Id

请求示例

请求头

POST /api/proxy/blockComplete HTTP/1.1
Host: upload.media.aliyun.com
Content-Length: 909
Content-Type: multipart/form-data; boundary=kONZAxLq3nZHHin6UICWVIORf4eY_Vf
Accept-Encoding: gzip,deflate
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.6 (java 1.5)
Authorization: UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

请求体

--kONZAxLq3nZHHin6UICWVIORf4eY_Vf
Content-Disposition: form-data; name="id"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

227435f9-0704-4fba-899c-8504b321f3d2
--kONZAxLq3nZHHin6UICWVIORf4eY_Vf
Content-Disposition: form-data; name="uploadId"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

F2F7A3150F13414C875BD2B4AE8EB459
--kONZAxLq3nZHHin6UICWVIORf4eY_Vf
Content-Disposition: form-data; name="parts"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

W3siZVRhZyI6IkM5NzIxOEQxQjAzMDUzNjQ0QjYxNjQ0RTI4NkE2N0I4IiwicGFydE51bWJlciI6IjEifSx7ImVUYWciOiJGNjg4MDA4NzA1NzI1RTFCQjg0MUJBMUY3RUFFMDc0OCIsInBhcnROdW1iZXIiOiIyIn0seyJlVGFnIjoiNEIwQ0RBNDg1RjA0M0EwNDZFNzY4ODdBNjhEQzM5RTEiLCJwYXJ0TnVtYmVyIjoiMyJ9LHsiZVRhZyI6Ijg3RTc1Q0IwQTIwOTVFNDgxOEE0MzREREZEMzkxNDBDIiwicGFydE51bWJlciI6IjQifV0
--kONZAxLq3nZHHin6UICWVIORf4eY_Vf--

返回示例

HTTP/1.1 200 OK
uploadId: F2F7A3150F13414C875BD2B4AE8EB459
dir: /
requestId: d5660bdf-03f4-42c5-98d8-b4c8df49f5f3
name: name
url: http://default-60011620.img.cdn.aliapp-inc.com/name

2.10 取消分片上传

请求Url: /api/proxy/blockCancel

请求头部: 参考公共请求头部

请求参数

参数	说明	必须	参数位置
id	上传唯一id	是	Body
uploadId	分片上传Id	是	Body

返回参数

无

请求示例

请求头

POST /api/proxy/blockCancel HTTP/1.1
Host: upload.media.aliyun.com
Content-Length: 438
Content-Type: multipart/form-data; boundary=le7YuC5yo1a4g3Kfp-tfDyHYgEvAvGyMs138
Accept-Encoding: gzip,deflate
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.6 (java 1.5)
Authorization: UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

请求体

--le7YuC5yo1a4g3Kfp-tfDyHYgEvAvGyMs138
Content-Disposition: form-data; name="id"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

d800bbb7-8ac6-4168-93a9-0dbfcdb37c54
--le7YuC5yo1a4g3Kfp-tfDyHYgEvAvGyMs138
Content-Disposition: form-data; name="uploadId"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DFDEC882C6244AB8981C9C9127104380
--le7YuC5yo1a4g3Kfp-tfDyHYgEvAvGyMs138--

返回示例

HTTP/1.1 200 OK

3、管理

3.1 资源ID

定义

根据REST风格的API，资源id用来唯一标识一个资源（例如图片、文件夹），在本文中使用resourceId表示，内容为URL安全的Base64编码的JSON数组。图片和文件夹的resourceId生成过程如下：

图片资源ID

resourceIdBeforeEncoded = '["<namespace>","<dir>","<name>"]' 
resourceId = url_safe_base64(resourceIdBeforeEncoded)

文件夹资源ID

resourceIdBeforeEncoded = '["<namespace>","<dir>"]' 
resourceId = url_safe_base64(resourceIdBeforeEncoded)

字段说明

namespace：用户空间名，必须指定，但可以是空串，表示如果用户有默认空间的情况下使用默认空间

dir：文件夹路径，必须指定，必须以“/”开始，不能以“/”结束，根目录除外；不能存在连续的“/”，总长度不超过192字节

name：文件名，对于文件描述必须存在，对于文件夹描述，必须不存在。总长度不超过64字节

3.2 管理凭证

管理凭证是顽兔多媒体服务用于验证管理请求合法性的机制。建议仅在业务服务器端使用这一类凭证，避免意外授权导致滥用。

凭证算法

1）生成待加签的原始字符串

使用请求URL中的<path>或<path>?<query>与请求内容（HTTP Body）以及请求时间使用“\n”拼接起来
- path是http url中的一段相对路径，包含’/‘开头，不包含’?’之后的url参数
- query是http url中的参数部分
如无请求内容(HTTP Body),则第二部分为空串

无HTTP Body情况下

stringBeforeSign =  "<path>?<query>\n\n<date>"

无HTTP Body而且无query情况下

stringBeforeSign =  "<path>\n\n<date>"

有HTTP body情况下

signingStr =  "<path>?<query>\n<body>\n<date>"

有HTTP body而且无query情况下

signingStr =  "<path>\n<body>\n<date>"

date必须与http header当中的Date字段值一致，支持Rfc822格式的date，或者“毫秒”格式的date(如果获取的精度是秒级，需要乘以1000)。

示例

假设一个URLEncoded Form POST请求，url为 http://rs.media.aliyun.com/v3/files/resouceIdSample?a=b。发送的时间为2015-12-11 13:00:03:814

假设POST的内容为

name=%E5%B0%8F%E6%98%8E

注意: 使用post方法提交urlEncoded form时，在计算签名串和post的body中，所有的key value对都需要经过url encoded的编码。不然会出现wrong sign错误

urlEncode(key1)=urlEncode(value1)&urlEncode(key2)=urlEncode(value2) ...

则加签串为

stringBeforeSign = "/v3/files/resouceIdSample?a=b\nname=%E5%B0%8F%E6%98%8E\n1449810003814"

http header头中的Date字段

Date: 1449810003814

2）使用SK对上一步生成的原始字符串计算HMAC-SHA1签名

sign = hex(hmac_sha1(signingStr, "<SK>"))

转换hmac_sha1之后得到的byte数组需要转成hex字符，hex字符字母为“全小写字符”

假设我的sk是1234，则得到的值是

sign = 38b09faf6e2939eeb21def18bfcc228d06fe13f1

3）将签名与AK进行拼接

preencode = <AK>:sign

假设我的ak是1234，则得到的值是

1234:38b09faf6e2939eeb21def18bfcc228d06fe13f1

4）对拼接后的结果进行URL安全的Base64编码

encoded = urlsafe_base64_encode(preencode)

上面的结果编码后是

encoded = MTIzNDozOGIwOWZhZjZlMjkzOWVlYjIxZGVmMThiZmNjMjI4ZDA2ZmUxM2Yx

5）最后为编码结果加上<type>得到管理凭证

manageToken = <type> <encoded>

百川的鉴权Type统一为:ACL_TOP

manageToken = ACL_TOP <encoded>

上面的结果加上Type后是

manageToken = ACL_TOP MTIzNDozOGIwOWZhZjZlMjkzOWVlYjIxZGVmMThiZmNjMjI4ZDA2ZmUxM2Yx

将上述得到的结果放置在http header的Authorization字段, 就完成了鉴权操作

Authorization: <manageToken>

上面的结果放置在http header后是

Authorization: ACL_TOP MTIzNDozOGIwOWZhZjZlMjkzOWVlYjIxZGVmMThiZmNjMjI4ZDA2ZmUxM2Y

3.3 公共请求头

公共请求头包含Authorizatio和Date两个头，分别说明如下：

Authorization

Authorization : type urlsafe_base64_encode(accessKey: hmac_sha1(uri=<path>?<query>\ndate=<rfc822 date>, "<SK>"))

详情参见管理凭证一节。

Date

格式：Date:date，其中date为RFC822格式的时间

注意：该Date的值与计算管理凭证时使用的Date必须一致，否则将鉴权失败。注意：请求中的DATE时间和多媒体服务器的时间差正负15分钟以上，多媒体服务器将拒绝该服务，并返回HTTP 401错误。

3.4 返回错误体

Body格式

{
    code: “子错误码”
    msg: “错误信息”
    requestId: "请求Id"
}

公共错误

resourceId等url内参数或者参数列表的参数错误，统一返回400并带子错误码InvalidArgument

认证错误统一返回401并带子错误码AuthenticationFailed

内部处理错误或其他未知错误统一返回500并带子错误码InternalError

3.5 管理服务器地址

目前，管理服务器的地址是：

http://rs.media.aliyun.com

3.6 删除文件

请求格式

DELETE /3.0/files/<resourceId>
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

404:文件不存在，子错误码为ResourceNotFound

有错误body返回

3.7 重命名文件

请求格式

POST /3.0/files/{resourceId}/rename/{newResourceId}
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

400:参数错误,子错误码为NameDuplicated,名称重复；

400:参数错误,子错误码为LimitExceeded,超过文件大小限制;

404:文件不存在，子错误码为ResourceNotFound

有错误body返回

特别注意

目前重命名接口背后存在数据流的拷贝，所以限制大小为100MB,请慎用；

3.8 文件是否存在

请求格式

GET /3.0/files/<resourceId>/exist
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

404:文件不存在，子错误码为ResourceNotFound

有错误body返回

3.9 获取文件meta信息

请求格式

GET /3.0/files/<resourceId>
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

404: 资源不存在，子错误码为ResourceNotFound

有错误body返回

3.10 获取文件列表

请求格式

GET /3.0/files?namespace=<namespace>&dir=<dir>&currentPage=<currentPage>&pageSize=<pageSize>
Date:<date> 
Authorization:<Authorization>

参数描述

namespace：同resourceId中namespace

dir：同resourceId中dir

currentPage：当前页码，从1开始

pageSize：当前页内文件个数，最大100

200:成功

400:参数错误，子错误码为InvalidArgument

404:资源不存在，子错误码为ResourceNotFound

有错误body返回

返回结果Body json格式：

{
    totalCount: 总数
    totalPage: 页数
    result: [
        {
            namespace: “名称空间”
            name: “文件名”
            path: “文件全路径”
            dir: “文件全路径”
            createStamp: “创建时间”
            modifyStamp “最后修改时间”
            etag: “目标资源的hash值，可用于http eTag头部”
            mineType: “文件元类型”
            size: “文件大小”
            url: “文件访问url”
        },
        …
    ]
}

3.11 创建文件夹

请求格式

POST /3.0/folders/<resourceId>
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

400：资源已存在，子错误码为NameDuplicated

有错误body返回

3.12 删除文件夹

请求格式

DELETE /3.0/folders/<resourceId>
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

400:文件夹非空，子错误码为NonEmpty

404:文件不存在，子错误码为ResourceNotFound

有错误body返回

3.13 文件夹是否存在

请求格式

GET /3.0/folders/<resourceId>/exist
Date:<date> 
Authorization:<Authorization>

参数描述

无

200:成功

404:资源不存在，子错误码为ResourceNotFound

有错误body返回

3.14 获取子文件夹列表

请求格式

GET  /3.0/folders
Date:<date> 
Authorization:<Authorization>

参数描述

namespace：同resourceId中namespace

dir：同resourceId中dir

currentPage：当前页码，从1开始

pageSize：当前页内文件个数，最大100

200:成功

400:参数错误，子错误码为InvalidArgument

404:文件不存在，子错误码为ResourceNotFound

有错误body返回

返回结果Body json格式：

{
    totalCount: 总数
    totalPage: 页数
    result: [
        {
            namespace: “名称空间”
            name: “目录名”
            path: “目录全路径”
            createStamp: “创建时间”
            modifyStamp “最后修改时间”
        },
        …
    ]
}

3.15 多媒体转码服务

请求格式

POST  /3.0/mediaEncode
Host: rs.media.aliyun.com
Date: <date> 
Authorization: <Authorization>
Content-Type: application/x-www-form-urlencoded
input=<input>&output=<output>&watermark=<watermark>&encodeTemplate=<encodeTemplate>&watermarkTemplate=<watermarkTemplate>&usePreset=<usePreset>&force=<force>&notifyUrl=<notifyUrl>

参数描述

参数	必须	类型	说明
input	是	ResourceId	见资源id，3.1节
output	是	ResourceId	见资源id，3.1节
watermark	否	ResourceId	见资源id，3.1节
encodeTemplate	是	String	模板名称，可以设置系统模板或者用户自定义模板。用户模板名称可以登录后台查看和设置，系统模板见附录系统模板列表
watermarkTemplate	否	String	用户自定义水印模板。水印模板名称可以登录后台查看和设置
usePreset	是	Boolean	是否使用系统模板，默认false。如果true，则encodeTemplate必须设置系统模板名称
force	是	Boolean	默认false，如果true，当output文件已经存在的时候会强制覆盖，否则不执行转码并结束任务
notifyUrl	否	String	通知url，任务结束之后会调用这个url，method为POST, Content-Type: application/json。见3.14.1节
seek	否	Double	截取音视频的开始位置
duration	否	Double	截取音视频的长度

200:成功

400:参数错误，子错误码为InvalidArgument

有错误body返回

成功返回结果Body json格式：

{
    "taskId": <taskId>
}

3.15.1 处理结果通知

服务端完成转码操作后，会由多媒体云往 isv 服务器发起请求，将处理结果状态提交给上一步操作中的‘notifyURL’指向的网址。

通知语法

POST <notifyURI> HTTP/1.1
Host: <notifyDomain>
Content-Type: application/json

<body>

头部信息

头部名称	必须	说明
Host	是	notifyURL的服务器域名。
Content-Type	是	固定为application/json。

通知内容

开发者获得的通知信息是一个JSON字符串，示例如下：

{
    "id": "55a984a5949da43251917a6f4cb2b9b0017ecc65e818"
    "tasks": [
        {
            "command": "{\"encodeTemplate\":\"video-generic-AVC-320x240\",\"usePreset\":true}",
            "description": "Task success",
            "input": {
                "dir": "/",
                "name": "test.mp4",
                "namespace": "test"
            },
            "output": {
                "dir": "/转码后的文件",
                "name": "testPOPS",
                "namespace": "test"
            },
            "progress": "100",
            "status": 4
        },
        {
            "command": "{\"encodeTemplate\":\"video-generic-AVC-320x240\",\"usePreset\":true}",
            "description": "Task success",
            "input": {
                "dir": "/",
                "name": "mulou8.mp4",
                "namespace": "qinning2"
            },
            "output": {
                "dir": "/转码后的文件",
                "name": "testPOPS",
                "namespace": "test"
            },
            "progress": "100",
            "status": 4
        }
    ]
}

转码结果状态表

状态码	说明
0	任务添加
1	任务运行中
2	任务启动失败
3	任务执行失败
4	任务执行成功

3.16 多媒体转码任务查询

请求格式

GET /3.0/mediaEncodeResult/<taskId> HTTP/1.1
Host: rs.media.aliyun.com
Content-Type: text/html
Authorization: <Authorization>
Date:<Date>

参数描述

请求参数以uri路径的一部分方式，拼接在mediaEncodeResult后面

头部名称	必须	说明
taskId	是	多媒体转码任务id。即4节调用媒体转码的返回值。

响应内容

同3.15节的通知内容

3.17 黄图扫描接口

请求格式

POST /3.1/scanPorn HTTP/1.1
Host: rs.media.aliyun.com
Content-Type: application/x-www-form-urlencoded
Authorization: <Authorization>
Date:<Date>

resourceId=<resourceId>

参数描述

resourceId 资源id列表，以“;”分隔。资源id格式见3.1

例子：

WyJxaW5uaW5nMiIsIi9tbHRlc3QiLCJwb3JuMCJd;WyJxaW5uaW5nMiIsIi9tbHRlc3QiLCJwb3JuMCJd

200:成功

400:参数错误，子错误码为InvalidArgument

成功返回值

{
    "message": "success",
    "result": [
        {
            "file": {
                "dir": "/test",
                "name": "porn0",
                "namespace": "imagedemo"
            },
            "message": "success",
            ,
            "score": 0.09,
            "status": 0,
            "type": 0,

        }
    ],
    "status": 0
}

返回参数

参数	类型	说明
message	String	返回消息
result	List	每个文件的扫描结果
status	int	见附录第二节
file	Object	dir: 文件夹名; name: 文件名； namespace: 空间名
score	double	[0-1] 黄图分值，越高则黄图嫌疑越高
type	int	0或者1，系统默认的黄图分值阈值是0.8。0.8之下的为非黄图，对应的type是0。0.8之上的图片是黄图，对应的type是1

3.18 图片扫描结果反馈接口

请求格式

POST /3.0/feedback HTTP/1.1
Host: rs.media.aliyun.com
Content-Type: application/x-www-form-urlencoded
Authorization: <Authorization>
Date:<Date>

feedback=<feedback0>&feedback=<feedback1>...

参数描述

feedback 可以一个或者多个，格式为json, 必须被urlencode过，编码是utf-8。json例子：

{
    "file": {
        "dir": "/test",
        "name": "test.jpg",
        "namespace": "imagedemo"
    },
    "type": 0,
    "wrong": true,
    "score": 1
}

feedback参数

参数	必须	类型	说明
file	是	Object	dir: 文件夹名; name: 文件名； namespace: 空间名
type	是	int	0或者1，0是非黄图，1是黄图
score	否	double	[0-1] 黄图分值，越高则黄图嫌疑越高
wrong	是	Boolean	true代表用户认为多媒体鉴黄服务的结果有问题，反馈给多媒体云用于提升算法准确率，当为true的时候必须传score。false代表用户提交的，有益于算法提升的样本，为false的时候不需要提交score

3.19 视频截图

请求格式

POST  /3.0/snapshot
Host: rs.media.aliyun.com
Date: <date> 
Authorization: <Authorization>
Content-Type: application/x-www-form-urlencoded
input=<input>&output=<output>&time=<time>&notifyUrl=<notifyUrl>

参数描述

参数	必须	类型	说明
input	是	ResourceId	见资源id，3.1节
output	是	ResourceId	见资源id，3.1节
notifyUrl	否	String	通知url，任务结束之后会调用这个url，method为POST, Content-Type: application/json。body: 见3.18节的返回
time	是	Integer	视频截图的位置，单位为毫秒

200:成功

400:参数错误，子错误码为InvalidArgument

有错误body返回

成功返回结果Body json格式：

{
    "taskId": <taskId>
}

3.20 视频截图结果查询

请求格式

GET  /3.0/snapshotResult/<taskId>
Host: rs.media.aliyun.com
Date: <date> 
Authorization: <Authorization>
Content-Type: application/x-www-form-urlencoded

参数描述

请求参数以uri路径的一部分方式，拼接在mediaEncodeResult后面

头部名称	必须	说明
taskId	是	视频截图任务id。即3.17节调用视频截图的返回值。

200:成功

400:参数错误，子错误码为InvalidArgument

有错误body返回

成功返回结果Body json格式：

{
    "status": "4",
    "requestId": "cb996eb494974509bf79f59cfbbf4484",
    "description": "Task success"
}

转码结果状态表

状态码	说明
0	任务添加
1	任务运行中
2	任务启动失败
3	任务执行失败
4	任务执行成功

3.21 广告图扫描接口(beta)

广告图接口公测中

请求格式

POST /3.1/scanAdvertising HTTP/1.1
Host: rs.media.aliyun.com
Content-Type: application/x-www-form-urlencoded
Authorization: <Authorization>
Date:<Date>

resourceId=<resourceId>

参数描述

resourceId 资源id列表，以“;”分隔。资源id格式见3.1

例子：

WyJxaW5uaW5nMiIsIi9tbHRlc3QiLCJwb3JuMCJd;WyJxaW5uaW5nMiIsIi9tbHRlc3QiLCJwb3JuMCJd

200:成功

400:参数错误，子错误码为InvalidArgument

成功返回值

{
    "message": "success",
    "result": [
        {
            "file": {
                "dir": "/test",
                "name": "advertising.jpg",
                "namespace": "imagedemo"
            },
            "message": "success",
            "score": 0.09,
            "status": 0,
            "type": 0
        }
    ],
    "status": 0
}

返回参数

参数	类型	说明
message	String	返回消息
result	List	每个文件的扫描结果
status	int	见下表
file	Object	dir: 文件夹名; name: 文件名； namespace: 空间名
score	double	[0-1] 广告图分值，越高则广告图嫌疑越高
type	int	0或者1，系统默认的广告图分值阈值是0.5。0.5之下的为非广告图，对应的type是0。0.5之上的图片是广告图，对应的type是1

状态码

状态码	说明
0	成功
100	服务器内部错误
10	其他错误，具体原因见message

4、附录

4.1. 预设表

预设名称	说明
video-generic-AVC-1080P	/format/mp4/vCodec/H.264/vBitrate/5400/vFps/30/vWidth/1920/vHeight/1080/aCodec/aac/aSamplerate/44100/aBitrate/160
video-generic-AVC-320x240	/format/mp4/vCodec/H.264/vBitrate/300/vFps/30/vWidth/320/vHeight/240/aCodec/aac/aSamplerate/22050/aBitrate/128
video-generic-AVC-360p-16_9	/format/mp4/vCodec/H.264/vBitrate/720/vFps/30/vWidth/640/vHeight/360/aCodec/aac/aSamplerate/44100/aBitrate/128
video-generic-AVC-360p-4_3	/format/mp4/vCodec/H.264/vBitrate/600/vFps/30/vWidth/480/vHeight/360/aCodec/aac/aSamplerate/44100/aBitrate/128
video-generic-AVC-480p-16_9	/format/mp4/vCodec/H.264/vBitrate/1200/vFps/30/vWidth/854/vHeight/480/aCodec/aac/aSamplerate/44100/aBitrate/128
video-generic-AVC-480p-4_3	/format/mp4/vCodec/H.264/vBitrate/900/vFps/30/vWidth/640/vHeight/480/aCodec/aac/aSamplerate/44100/aBitrate/128
video-generic-AVC-720p-16_9	/format/mp4/vCodec/H.264/vBitrate/2400/vFps/30/vWidth/1280/vHeight/720/aCodec/aac/aSamplerate/44100/aBitrate/160
video-HLS-1000K	/format/m3u8/vCodec/H.264/vBitrate/1000/vFps/30/aCodec/aac/aSamplerate/44100/aBitrate/128
video-HLS-150K	/format/m3u8/vCodec/H.264/vBitrate/150/vFps/30/aCodec/aac/aSamplerate/44100/aBitrate/128
video-HLS-240K	/format/m3u8/vCodec/H.264/vBitrate/240/vFps/30/aCodec/aac/aSamplerate/44100/aBitrate/128
video-HLS-640K	/format/m3u8/vCodec/H.264/vBitrate/640/vFps/30/aCodec/aac/aSamplerate/44100/aBitrate/128
video-web	/format/mp4/vCodec/H.264/vBitrate/2200/vFps/30/vWidth/1280/vHeight/720/aCodec/aac/aSamplerate/44100/aBitrate/160

预设参数说明

预设参数	说明
format	输出格式。目前支持flv、m3u8(默认切片大小为10s)、mp4。
vFps	视频帧率。值范围[0,60]。
vCodec	编解码格式,默认值H.264。
vGop	关键帧最大帧数。值范围[1,100000],默认250。
vProfile	编码级别。默认high。
vBitrate	视频输出文件的码率,值范围[10,50000],单位kbps。
vCrf	码率-质量控制因子,[0 51],如果设置了Crf,则Bitrate的设置失效,默认值26。
vWidth	宽,默认值是视频原始宽度,值范围[64,4096]。
vHeight	高,默认值是视频原始高度,值范围[64,4096]。
vPreset	视频算法器预置,默认值slow,支持veryfast、fast、medium、slow、slower、veryslow。
vScanMode	扫描模式,支持interlaced、progressive。
vMaxrate	视频码率峰值,值范围[10,50000],单位kbps。
vBufsize	缓冲区大小,默认值6000,值范围[1000,128000],单位kb。
aCodec	音频编解码格式,aac、mp3,默认是aac。
aSamplerate	采样率,默认值是44100,可选22050、32000、44100、48000、96000,单位为Hz。
aBitrate	输出文件的音频码率,值范围[8,1000],单位kbps,默认值128。
aChannels	声道数,默认值是2,目前仅支持双声道。

4.2. 鉴黄服务结果状态表

状态码	说明
0	成功
100	服务器内部错误
2	文件下载失败
3	文件类型错误，只支持jpg，png，bmp文件扫描
4	url格式错误
5	文件太大，只支持10m以下文件扫描
6	文件下载超时

4.3. 上传策略-视频转码参数

4.3.1 MediaEncodePolicy

字段名称	类型	是否必须	说明
notifyUrl	String	否	指定视频转码回调地址
tasks	MediaEncodeTask[]	是	为MediaEncodeTask列表， MediaEncodeTask类型说明具体见4.3.2

4.3.2 MediaEncodeTask

字段名称	类型	是否必须	说明
output	File	是	指定视频转码输出地址, 类型说明具体见4.4
watermark	File	否	指定视频转码水印地址, 类型说明具体见4.4
encodeTemplate	String	是	指定视频转码模板
watermarkTemplate	String	否	指定视频转码水印模板
usePreset	String	否	true代表使用系统模板， false代表使用用户模板
duration	String	否	截取的时长，与restapi中一致
seek	String	否	截取的开始时间，与restapi中一致
force	String	否	true 代表强制覆盖，false代表不覆盖。默认为不覆盖

4.4 File

字段名称	类型	是否必须	说明
dir	String	是	文件夹地址，以'/'开头, 不以'/'结尾。比如: 根路径: '/' test文件夹: '/test'
name	String	是	文件名
namespace	String	是	空间名

FAQ

关于此文档暂时还没有FAQ

有用(18) 我要提问

开放平台

多媒体服务

REST API

1、约定

2、上传

2.1 上传策略

2.2 占位符

2.3 上传凭证

1.构造上传策略

2.将上传策略格式化为JSON格式

3.对JSON编码的上传策略进行URL安全的Base64编码（详情参见RFC4648 ）

4.使用SK对编码后的上传策略计算HMAC-SHA1签名

5.将AK、encodedPolicy和sign用“ ：”连接起来，再一次进行URL安全的Base64编码，并加上前缀 “UPLOAD_AK_TOP”

6.上传凭证需要在文件上传时包含在HTTP的Authorization 头中，示例为：

2.4 公共请求头

2.5 上传服务器地址

2.6 普通上传

2.7 初始化分片上传

2.8 分片上传

2.9 分片上传完成

2.10 取消分片上传

3、管理

3.1 资源ID

3.2 管理凭证

凭证算法

3.3 公共请求头

3.4 返回错误体

3.5 管理服务器地址

3.6 删除文件

3.7 重命名文件

3.8 文件是否存在

3.9 获取文件meta信息

3.10 获取文件列表

3.11 创建文件夹

3.12 删除文件夹

3.13 文件夹是否存在

3.14 获取子文件夹列表

3.15 多媒体转码服务

3.15.1 处理结果通知

3.16 多媒体转码任务查询

响应内容

3.17 黄图扫描接口

3.18 图片扫描结果反馈接口

3.19 视频截图

3.20 视频截图结果查询

3.21 广告图扫描接口(beta)

4、附录

4.1. 预设表

预设参数说明

4.2. 鉴黄服务结果状态表

4.3. 上传策略-视频转码参数

4.3.1 MediaEncodePolicy

4.3.2 MediaEncodeTask

4.4 File

FAQ