友盟+搜索

{{errorMsg}}

约定

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

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

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

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

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

上传

上传策略

      上传策略是提供给开发者用于控制上传相关行为与限制的一个配置设定。为了防止传输过程中对上传策略进行篡改,上传策略将作为签名字段包含在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>"
}

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

字段名称

是否必须

说明

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的过期时间

举例如下:

(System.currentTimeMillis() + 3600 * 1000)表示该Token一小时后失效

占位符

上传策略中有些策略(例如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

上传文件的大小

width

图片宽

height

图片高

exif

图片的Exif信息,里面包含了诸多子项

可以通过exif.xxx来获取

自定义占位符

var-*

用户自定义占位符("var-"为参数前缀, "*"为用户用于渲染的自定义占位符名),包含在上传参数中

自定义元信息

meta-*

用户自定义的文件meta信息("meta-"为参数前缀, "*"为用户用于渲染的自定义Meta信息名) ,包含在上传参数中

注意:

当发生重名时, 会以该顺序进行选择: 系统占位符、用户自定义文件meta占位符、用户自定义占位符。在上传的时候, 如果需要指定一个名称为cat的占位符, 需要使用名称为var-cat的参数声明该自定义占位符;meta则对应meta-cat。

上传凭证

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

计算方法

1.构造上传策略

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

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

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

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

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

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

uploadPolicy='{"namespace":"myspace","expiration":1451491200,"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 = hmac_sha1(encodedPolicy, "<SecretKey>")

得到:

184eeb1d1673b761dc87ab7eb3dba7e2890cf016

5.将AK、encodedPolicy和sign用“ :”连接起来,再一次进行URL安全的Base64编码,并加上前缀 “UPLOADAKTOP”
uploadToken = UPLOAD_AK_TOP  url_safe_base64(AccessKey + ':' + encodedPolicy + ':' + sign)

即是最后的上传凭证。

6.上传凭证需要在文件上传时包含在HTTP的Authorization 头中,示例为:
Authorization : UPLOAD_AK_TOP YXBwX2tleTpleUprWlhSbFkzUk5hVzFsSWpveExDSmxlSEJwY21GMGFXOXVJam90TVN3aWFXNXpaWEowVDI1c2VTSTZNU3dpYm1GdFpYTndZV05sSWpvaWJtRnRaWE53WVdObElpd2ljMmw2WlV4cGJXbDBJam93ZlE6MTg0ZWViMWQxNjczYjc2MWRjODdhYjdlYjNkYmE3ZTI4OTBjZjAxNg

公共请求头

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

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

说明:

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

uploadPolicy: 用户的上传策略

signature: hmac_sha1(base64(uploadPolicy), accessKeySecret)

base64: URLSafe Base64 编码

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

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

上传服务器地址

上传服务器域名:

http://upload.media.aliyun.com

普通上传

请求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

文件md5值

请求示例

请求头

PUT /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

初始化分片上传

请求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

上传部分的md5值

请求示例

请求头

PUT /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

分片上传

请求Url: /api/proxy/blockUpload

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

请求参数

参数

说明

必须

参数位置

md5

文件md5值

否(推荐提供此参数进行一致性检查)

Body

id

上传唯一id

Body

uploadId

分片上传Id

Body

partNumber

块编号

Body

content

分片内容

是(必须位于参数的最后一位)

Body

size

分片大小

Body

返回参数

参数

说明

partNumber

块编号

ETag

上传部分的md5值

请求示例

请求头

PUT /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

分片上传完成

请求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

请求示例

请求头

PUT /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

取消分片上传

请求Url: /api/proxy/blockCancel

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

请求参数

参数

说明

必须

参数位置

id

上传唯一id

Body

uploadId

分片上传Id

Body

返回参数

请求示例

请求头

PUT /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

管理

资源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字节

管理凭证

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

凭证算法

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

  • 使用请求URL中的或?与请求内容(HTTP Body)以及请求时间使用"\n"拼接起来
  • 如无请求内容(HTTP Body),则第二部分为空串

无HTTP Body情况下

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

有HTTP body情况下

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

示例

假设url为 http://rs.media.aliyun.com/v3/files/resouceIdSample

stringBeforeSign = "v3/files/resouceIdSample\n\n1426605685813"

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

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

3.将签名与AK进行拼接

preencode = <AK>:sign

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

encoded = urlsafe_base64_encode(preencode)

5.最后为编码结果加上得到管理凭证

manageToken = <type> encoded

公共请求头

公共请求头包含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错误。

返回错误体

Body格式

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

公共错误

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

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

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

管理服务器地址

目前,管理服务器的地址是:

http://rs.media.aliyun.com

删除文件

请求格式

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

参数描述

返回

200:成功

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

有错误body返回

文件是否存在

请求格式

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

参数描述

返回

200:成功

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

有错误body返回

获取文件meta信息

请求格式

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

参数描述

返回

200:成功

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

有错误body返回

获取文件列表

请求格式

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 “最后修改时间”
            md5: “文件md5信息”
            mineType: “文件元类型”
            size: “文件大小”
            url: “文件访问url”
        },
        …
    ]
}

创建文件夹

请求格式

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

参数描述

返回

200:成功

400:资源已存在,子错误码为NameDuplicated

有错误body返回

删除文件夹

请求格式

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

参数描述

返回

200:成功

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

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

有错误body返回

文件夹是否存在

请求格式

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

参数描述

返回

200:成功

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

有错误body返回

获取子文件夹列表

请求格式

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 “最后修改时间”
        },
        …
    ]
}

多媒体转码任务查询

请求格式

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.14节的通知内容

黄图扫描接口

请求格式

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

图片扫描结果反馈接口

请求格式

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

附录

预设表

预设名称 说明
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,目前仅支持双声道。

鉴黄服务结果状态表

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