最近更新时间:2024-03-22 19:08:00
支持上传回调处理的接口有PUT Object、Complete Multipart Upload、POST Object
在调用PUT Object、Complete Multipart Upload接口时,可携带相关的Callback参数,实现上传回调处理(Upload CallBack Processing,UCP)。
客户端将文件及相关Callback请求头上传到KS3后,KS3会通过POST方法向用户的回调地址POST一段JSON数据,此JSON数据为客户端传入的x-kss-callbackbody
请求头填充变量后转化得来。用户服务端正确处理回调后返回{"result":true}
,如果回调处理错误返回{"result":false}
,则表示文件上传失败,如果用户服务端没有返回任何消息,则进入超时等待,默认等待时间为3秒,重试两次。只有在KS3服务端收到{"result":true}
时,文件才真正上传成功。
支持的头部参数里面加入x-kss-callbackauth
值为”1”时表示开启回调鉴权功能,具体详见第三部分“回调鉴权”。
上传回调请求保持原有接口不变。
该接口不使用请求参数。
名称 | 描述 | 是否必选 |
---|---|---|
x-kss-callbackurl | 支持HTTP和HTTPS,接收回调的服务器地址 | 是 |
x-kss-callbackbody | 发起回调时请求Body的值。回调参数支持自定义参数返回、常量和魔法变量,自定义变量通过Header传回,例如objectKey=${key}&etag=${etag}&uid=123 | 是 |
x-kss-callbackauth | 值为”1”时表示开启回调鉴权功能。回调鉴权功能具体详见第三部分“回调鉴权” | 否 |
kss-* | 请求时如果带kss-开头的Header,回调时也会带上 | 否 |
参数 | 说明 | 备注 |
---|---|---|
bucket | 文件上传的Bucket | Utf-8编码 |
key | 文件的名称 | Utf-8编码 |
etag | 文件MD5值经过Base64处理 | |
objectSize | 文件大小 | 以字节标识 |
mimeType | 文件类型 | |
createTime | 文件创建时间 | Unix时间戳表示,1420629372,确切到秒 |
应用服务器返回响应给KS3,返回的回调内容需要包含:
指定的回调内容:{“result”:“true”}或{“result”:“false”}。如返回的内容不包含该内容,则回调失败(同时上传也会失败)。
其他回调内容:Body体大小不能超过1MB,内容需为JSON格式。如果Body体大小超过1MB,则回调失败(同时上传也会失败)。
例如返回的回调请求为:
HTTP/1.0 200 OK
Server: BaseHTTP/0.3 Python/2.7.6
Date: Mon, 14 Sep 2021 12:37:27 GMT
Content-Type: application/json
{
"result":"true",
"a":"b"
}
回调成功后,KS3将回调应用服务器返回的内容返回给用户。如回调失败,将返回400 CallbackFail
HTTP/1.1 200 OK
Date: Mon, 14 Sep 2015 12:37:27 GMT
Content-Type: application/json
Content-Length: 120
Connection: close
ETag: "1b2cf535f27731c974343645a398****"
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3
{
"result":"true",
"a":"b"
}
回调失败,将返回400 CallbackFail
采用POST回调时,需要在请求后面加入一个postcallback的参数,如POST /?postcallback HTTP/1.1
,表示这是一个POST回调请求。当加入postcallback参数时,表单项中必须同时存在回调相关的参数,否则请求会判定不合法,具体与回调服务器交互过程与PUT回调一致。其它语法和普通POST请求一样。
上传回调请求保持原有接口不变,参考Post Object。
参数 | 描述 | 是否必选 |
---|---|---|
postcallback | 表示这是一个POST回调请求 | 是 |
名称 | 描述 | 是否必选 |
---|---|---|
x-kss-callbackurl | 支持HTTP和HTTPS,接收回调的服务器地址 | 是 |
x-kss-callbackbody | 回调参数支持自定义参数返回、常量和魔法变量,自定义变量通过Header传回,例如objectKey=${key}&etag=${etag}&uid=123 | 是 |
x-kss-callbackauth | 值为”1”时表示开启回调鉴权功能。回调鉴权功能具体详见第三部分“回调鉴权” | 否 |
kss-* | 请求时如果带kss-开头的Header,回调时也会带上 | 否 |
参数 | 说明 | 备注 |
---|---|---|
bucket | 文件上传的Bucket | Utf-8编码 |
key | 文件的名称 | Utf-8编码 |
etag | 文件MD5值经过Base64处理 | |
objectSize | 文件大小 | 以字节标识 |
mimeType | 文件类型 | |
createTime | 文件创建时间 | Unix时间戳表示,1420629372,确切到秒 |
回调响应内容与Put Object回调内容及方式一致。
调用POST回调方法时,如果未传入回调必填的表单项,请求将返回400。如果传入了回调相关的表单项,但是调用的是普通(非回调)POST方法时,请求也会返回400。
如果回调时用户开启了鉴权字段x-kss-callbackauth(该字段在PUT和Complete Multipart Upload请求中写在Header里,在POST请求中写在表单项里)则KS3向用户的回调地址返回的Header中,就会包含Authorization和x-kss-date字段内容:
Authorization: ks3cbauth AKLTtxxxxx5IxxxpA7xxxxxx:FIexxyY3jGe07JxxxxxW5rBejKM=
x-kss-date:1590132647609
其中ks3cbauth为固定值,AKLT开头到冒号前内容为用户此条POST请求使用的AK,冒号后面的部分是用此AK、对应SK和服务端指定时间(此处x-kss-date为回调发起时间即KS3服务器的时间)算出的签名串signature,算签名的方法和发送请求的V2签名计算方法类似,但简化一些。
signString = "ksscallback " + {timestamp} //形如"ksscallback 1590132647609",中间有个空格,ksscallback是个固定值
signature = Base64(HMAC-SHA1(YourSecretKey, UTF-8-Encoding-Of(signString)));
纯净模式