上传回调处理

支持上传回调处理的接口有PUT Object、COMPLETE MULTIPART UPLOAD、POST Object

1.PUT Object、COMPLETE MULTIPART UPLOAD

描述

在调用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”时表示开启回调鉴权功能，具体详见第三部分“回调鉴权”。

请求接口

上传回调请求保持原有接口不变，参考Put Object,Complete Multipart Upload。

请求参数

该接口不使用请求参数。

请求头部

名称	描述	是否必选
x-kss-callbackurl	支持http和https,接收回调的服务器地址	是
x-kss-callbackbody	回调参数支持自定义参数返回、常量和魔法变量，自定义变量通过Header传回，例如objectKey=${key}&etag=${etag}&uid=123 回调参数的value值不能包含“=”和“&”	是
x-kss-callbackauth	值为”1”时表示开启回调鉴权功能。回调鉴权功能具体详见第三部分“回调鉴权”	否
kss-location	自定义头以kss-开始	自定义

魔法变量

参数	说明	备注
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: "D8E8FCA2DC0F896FD7CB4CB0031BA249"
Server: KS3

{
"result":"true",
"a":"b"
}

特殊错误

回调失败，将返回400 CallbackFail

2.POST Object

描述

采用POST回调时，需要在请求后面加入一个postcallback的参数，如POST /?postcallback HTTP/1.1，表示这是一个POST回调请求。当加入postcallback参数时，表单项中必须同时存在回调相关的参数，否则请求会判定不合法，具体与回调服务器交互过程与PUT回调一致。其它语法和普通POST请求一样，参考Post Object。

请求接口

上传回调请求保持原有接口不变，参考Post Object。

请求参数

参数	描述	是否必选
postcallback	表示这是一个POST回调请求	是

表单项

名称	描述	是否必选
x-kss-callbackurl	支持http(s)	是
x-kss-callbackbody	回调参数支持自定义参数返回、常量和魔法变量，自定义变量通过Header传回，例如objectKey=${key}&etag=${etag}&uid=123 回调参数的value值不能包含“=”和“&”	是
x-kss-callbackauth	值为”1”时表示开启回调鉴权功能。回调鉴权功能具体详见第三部分“回调鉴权”	否
kss-location	自定义头以kss-开始	自定义

魔法变量

参数	说明	备注
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)));