You need to enable JavaScript to run this app.
导航

上传回调

最近更新时间2023.07.26 16:49:53

首次发布时间2023.03.15 10:51:51

上传回调是指客户端在请求时携带回调(Callback)参数,服务端在上传完成后,发送同步的 POST 回调请求到 CallBack 中指定的第三方应用服务器,在服务器确认接受并返回结果后,才将所有结果返回给客户端。由于加入了回调请求和等待响应的过程,相比于普通上传会有更多的等待时间。

上传回调说明

目前支持上传回调的接口如下:

上传回调的流程如下:

alt

上传回调构造参数

使用上传回调依赖客户端在请求时携带回调参数和回调参数变量。

回调参数

回调参数是一段经过 Base64 编码的 JSON 格式字符串。示例如下:

// 示例 1,传递 application/json 类型的消息体
{
    "callbackUrl" : "http://domainname.com/callback", 
    "callbackHost" : "alternative-domainname.com",               
    "callbackBody" : "{\"bucket\" : ${bucket}, \"object\" : ${object}, \"key1\" : ${x:key1}, \"key2\" : ${x:key2}}", 
    "callbackBodyType" : "application/json"                
}

// 示例 2,传递 application/x-www-form-urlencoded 类型的消息体
{
    "callbackUrl" : "http://domain-name/callback", 
    "callbackHost" : "alternative-domain-name",               
    "callbackBody" : "bucket=${bucket}&object=${object}&key1=${x:key1}&key2=${x:key2}", 
    "callbackBodyType" : "application/x-www-form-urlencoded"               
}

参数说明

字段
作用描述约束限制

callbackUrl

回调请求的 URL,用于指定回调请求的第三方应用服务的地址,TOS 服务在上传成功后会向该地址发送 HTTP/HTTPS 请求。

  • 回调参数可为空,为空时代表本次请求没有设置上传回调参数。

  • URL 格式为 HTTP/HTTPS 协议地址,不指定协议类型时,默认为 https://

  • URL 中的 path 和 query 部分必须经过 URL 编码。

  • 支持最多 5 个 URL,不同 URL 之间用分号 ; 分隔。TOS 服务端在回调请求时会按顺序依次请求,直至第一个返回成功的 URL 为止。

  • 不支持回调参数变量。

callbackHost

回调请求发送时的 HOST 头域,用于替换 callbackUrl 中解析出的 HOST。

  • 可为空,不为空时必须符合域名或 IP 的格式规则。

  • 不支持回调参数变量。

callbackBody

回调请求发送时的消息体,格式需与 callbackBodyType 指定的类型匹配。

  • 不可为空且必须为合法的格式,TOS 服务端会强校验该字段。

  • 支持回调参数变量。

callbackBodyType

回调请求的消息体类型(Content-Type),与 callbackBody 配套使用。

  • 可为空,为空时默认为 application/x-www-form-urlencoded。

  • 只支持 application/x-www-form-urlencoded 和 application/json 两种类型的值,其他值将被视为不合法。

  • 不支持回调参数变量。

注意

  • 当 callbackUrl 为空时,表示本次请求没有设置上传回调参数,此时其它参数无效。

  • callbackUrl 和 callbackHost 包含的域名或 IP 不能是特殊的域名和 IP,例如 127.0.0.1、0.0.0.0、0:0:0:0:0:0:0:1、0:0:0:0:0:0:0:0 及 localhost。

回调参数变量

回调参数中的 callbackBody 支持使用回调参数变量,分为系统内置变量和自定义变量(callback-var)两类,前者可以在 callbackBody 中直接使用,后者需要客户端在请求时一并携带。TOS 服务端会根据 JSON 格式解析出自定义变量并与系统内置变量合并为一组可用的键值对,用于 callbackBody 的中 ${variable_name} 和 ${x:variable_name} 形式变量的替换。

系统内置变量

callbackBody 中可以设置的系统内置变量请参见下表。

注意

  • 在 callbackBody 中使用系统内置变量时,必须添加 ${} 操作符,例如 ${bucket} 代表获取上传的桶名。

  • 当 callbackBodyType 为 application/json 时,作为 JSON 格式中的字段值会按照变量类型填充。例如 bucket 为字符串 bucket-test,size 为整型 1024,则 {"bucket": ${bucket}, "size" : ${size}} 解析后的值为 {"bucket-test" : "bucket-test", "size" : 1024}。

变量名
变量说明变量类型
bucket上传的桶名。string
key上传的对象名。string
object上传的对象名。string
size上传对象的大小。int64
etag上传后对象的 ETag。string
crc64ecma上传后对象的 CRC64。string
versionId上传后对象的版本号,只在桶开启了多版本特性时有值。string
filenamePostObject 上传的文件原名。string
fnamePostObject 上传的文件原名。string
mimeType上传对象时客户端指定的 Content-Type,客户端未指定时默认为 binary/octet-stream。string
requestId本次请求的 Request ID。string

自定义变量

客户端在请求时可携带 JSON 格式的自定义变量键值对,TOS 服务端会根据 JSON 格式解析出自定义变量用于 callbackBody 中变量的替换。如下所示,定义了四个自定义变量:

{
    "x:key1" : "value1",                 // 定义字符串类型的字段
    "x:key2" : 123,                      // 定义数字类型的字段
    "x:key3" : ["value2", "value3"],     // 定义数组类型的字段
    "x:key4" : true                      // 定义布尔类型的字段
}

注意

  • 自定义变量必须以 x: 开头,否则视为不合法。

  • 在 callbackBody 中使用自定义变量时,必须添加 ${} 操作符,例如 ${x:key1} 代表获取变量 x:key1。

  • 当 callbackBodyType 为 application/json 时,TOS 服务端的填充规则与使用系统内置变量时一致。

  • 当 callbackBodyType 为 application/x-www-form-urlencoded 时,callbackBody 中的系统变量(key、object、fname、filename)会在填充时被 url_encode 编码。

构造上传回调请求

上传回调支持的接口包括 PutObject、PostObject、CompleteMultipartUpload,其中 PutObject 及 CompleteMultipartUpload 可以使用 URL 或 Header 携带回调参数和自定义变量;PostObject 使用表单域携带回调参数和自定义变量。客户端构造上传回调请求的方式如下所示。

上传回调支持接口 支持的参数携带方式参数定义签名方式约束限制

PutObject CompleteMultipartUpload

Header 中携带参数

Header 使用:

  • x-tos-callback

  • x-tos-callback-var

按照签名机制计算到 CanonicalHeaders 和 SignedHeaders 中。

  • 两个变量都必须是经过 Base64 编码的 JSON 格式。

  • 不能在 Header 和 Query 上重复出现回调参数和自定义变量,但可以各包含一个实现组合。

URL 中携带参数

Query 使用:

  • x-tos-callback

  • x-tos-callback-var

按照签名机制计算到 CanonicalQueryString 中。

PostObject

使用 POST 表单域携带

  • 表单域使用 x-tos-callbac

  • 表单域使用 x-tos-callback-var 或通过表单域传递自定义变量各字段。

按照 POST 上传对象时的签名机制将 x-tos-callback、x-tos-callback-var 和自定义变量放入表单上传的 policy 中做为 conditions。

  • x-tos-callback 和 x-tos-callback-var 必须是经过 Base64 编码的 JSON 格式。

  • 优先使用 x-tos-callback-var,如果没有携带 x-tos-callback-var,则代表自定义变量的每个字段是通过表单域来传递的。

具体说明

  • 在 URL 中携带参数:通过 x-tos-callback 携带回调参数;通过 x-tos-callback-var 携带回调参数变量的自定义变量。

  • 在 Header 中携带参数: 通过 x-tos-callback 携带回调参数;通过 x-tos-callback-var 携带回调参数变量的自定变量。

  • 在 Post 请求的 body 中通过表单域来携带参数,通过 x-tos-callback 携带回调参数: 回调参数变量中的自定义变量通过 x-tos-callback-var 携带,如果没有携带 x-tos-callback-var,代表自定义变量的每个字段是通过表单域来单独传递的,例如:

    --9431149156168
    Content-Disposition: form-data; name="x:key1"
    value1
    --9431149156168
    Content-Disposition: form-data; name="x:key2"
    123
    

客户端上传回调构造示例

本文以第三方应用服务器对于 TOS 的回调请求返回响应 {"Status":"OK"},回调参数和回调参数变量如下为例,构造客户端上传回调请求:

// 回调参数: 
{
    "callbackUrl" : "http://domainname.com/callback", 
    "callbackHost" : "alternative-domainname.com",               
    "callbackBody" : "{\"bucket\" : ${bucket}, \"object\" : ${object}, \"key1\" : ${x:key1}, \"key2\" : ${x:key2}}", 
    "callbackBodyType" : "application/json"                
}

// 回调参数变量:
{
    "x:key1" : "value1",
    "x:key2" : 123,
}

// 第三方应用服务返回的结果:
{"Status":"OK"}

将回调参数和回调参数变量经过 Base64 编码

// 回调参数 Base64 Encode 得到 x-tos-callback: 
Cgl7CgkJImNhbGxiYWNrVXJsIiA6ICJodHRwOi8vZG9tYWlubmFtZS5jb20vY2FsbGJhY2siLCAKCQkiY2FsbGJhY2tIb3N0IiA6ICJhbHRlcm5hdGl2ZS1kb21haW5uYW1lLmNvbSIsICAgICAgICAgICAgICAgCgkJImNhbGxiYWNrQm9keSIgOiAie1wiYnVja2V0XCIgOiAke2J1Y2tldH0sIFwib2JqZWN0XCIgOiAke29iamVjdH0sIFwia2V5MVwiIDogJHt4OmtleTF9LCBcImtleTJcIiA6ICR7eDprZXkyfX0iLCAKCQkiY2FsbGJhY2tCb2R5VHlwZSIgOiAiYXBwbGljYXRpb24vanNvbiIgICAgICAgICAgICAgICAgCgl9
// 回调参数变量 Base64 Encode 得到 x-tos-callback-var:
ewogICAgIng6a2V5MSIgOiAidmFsdWUxIiwKICAgICJ4OmtleTIiIDogMTIzLAp9

构造 PutObject 请求并在 Header 中携带回调参数和自定义变量

PUT /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
x-tos-callback-var: ewogICAgIng6a2V5MSIgOiAidmFsdWUxIiwKICAgICJ4OmtleTIiIDogMTIzLAp9
x-tos-callback: Cgl7CgkJImNhbGxiYWNrVXJsIiA6ICJodHRwOi8vZG9tYWlubmFtZS5jb20vY2FsbGJhY2siLCAKCQkiY2FsbGJhY2tIb3N0IiA6ICJhbHRlcm5hdGl2ZS1kb21haW5uYW1lLmNvbSIsICAgICAgICAgICAgICAgCgkJImNhbGxiYWNrQm9keSIgOiAie1wiYnVja2V0XCIgOiAke2J1Y2tldH0sIFwib2JqZWN0XCIgOiAke29iamVjdH0sIFwia2V5MVwiIDogJHt4OmtleTF9LCBcImtleTJcIiA6ICR7eDprZXkyfX0iLCAKCQkiY2FsbGJhY2tCb2R5VHlwZSIgOiAiYXBwbGljYXRpb24vanNvbiIgICAgICAgICAgICAgICAgCgl9
Authorization: authorization_string
Content-Type: text/plain
Content-Length: 0

构造 CompleteMultipartUpload 请求并在 URL 中携带回调参数和自定义变量

POST /objectName?uploadId=UploadId&x-tos-callback=Cgl7CgkJImNhbGxiYWNrVXJsIiA6ICJodHRwOi8vZG9tYWlubmFtZS5jb20vY2FsbGJhY2siLCAKCQkiY2FsbGJhY2tIb3N0IiA6ICJhbHRlcm5hdGl2ZS1kb21haW5uYW1lLmNvbSIsICAgICAgICAgICAgICAgCgkJImNhbGxiYWNrQm9keSIgOiAie1wiYnVja2V0XCIgOiAke2J1Y2tldH0sIFwib2JqZWN0XCIgOiAke29iamVjdH0sIFwia2V5MVwiIDogJHt4OmtleTF9LCBcImtleTJcIiA6ICR7eDprZXkyfX0iLCAKCQkiY2FsbGJhY2tCb2R5VHlwZSIgOiAiYXBwbGljYXRpb24vanNvbiIgICAgICAgICAgICAgICAgCgl9&x-tos-callback-var=ewogICAgIng6a2V5MSIgOiAidmFsdWUxIiwKICAgICJ4OmtleTIiIDogMTIzLAp9 HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization_string

{
    "Parts":[{
        "PartNumber":1, 
        "ETag":"7de47c292287f7965357c1ddd724b2b7"
    }]
}

构造 PostObject 请求并在表单域携带回调参数和自定义变量

POST / HTTP/1.1
Host: buketname.tos-cn-beijing.volces.com
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length
--9431149156168
Content-Disposition: form-data; name="key"
objectname
--9431149156168
Content-Disposition: form-data; name="x-tos-callback"
Cgl7CgkJImNhbGxiYWNrVXJsIiA6ICJodHRwOi8vZG9tYWlubmFtZS5jb20vY2FsbGJhY2siLCAKCQkiY2FsbGJhY2tIb3N0IiA6ICJhbHRlcm5hdGl2ZS1kb21haW5uYW1lLmNvbSIsICAgICAgICAgICAgICAgCgkJImNhbGxiYWNrQm9keSIgOiAie1wiYnVja2V0XCIgOiAke2J1Y2tldH0sIFwib2JqZWN0XCIgOiAke29iamVjdH0sIFwia2V5MVwiIDogJHt4OmtleTF9LCBcImtleTJcIiA6ICR7eDprZXkyfX0iLCAKCQkiY2FsbGJhY2tCb2R5VHlwZSIgOiAiYXBwbGljYXRpb24vanNvbiIgICAgICAgICAgICAgICAgCgl9
--9431149156168
Content-Disposition: form-data; name="x:key1"
value1
--9431149156168
Content-Disposition: form-data; name="x:key2"
123
--9431149156168
Content-Disposition: form-data; name="x-tos-algorithm"
TOS4-HMAC-SHA256
--9431149156168
Content-Disposition: form-data; name="x-tos-date"
20220411T000000Z
--9431149156168
Content-Disposition: form-data; name="x-tos-credential"
<your-access-key-id>/<date>/<region>/<service>/request
--9431149156168
Content-Disposition: form-data; name="policy"
base64encoded_policy
--9431149156168
Content-Disposition: form-data; name="x-tos-signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to TOS
--9431149156168--

发起回调请求

TOS 服务端完成对象上传后,会根据上传请求中的回调参数配置发送 Post 请求调用第三方应用服务,第三方应用服务器实现的回调接口应满足以下约束。

约束项要求
接口协议HTTP、HTTPS,使用 HTTPS 协议时第三方应用服务必须有合法的证书。
支持方法POST
请求消息体格式application/x-www-form-urlencoded、application/json
响应状态码200
响应消息体格式application/json
响应消息体大小不超过 3MB。

TOS 根据用户请求中的回调参数和回调参数变量,使用 Post 请求调用第三方服务器,示例如下:

POST /callback HTTP/1.1
Host: alternative-domainname.com
Content-Length: 71
Content-Type: application/json

{"bucket":"bucket-test","object":"key-test","key1":"value1","key2":123}

返回回调结果

第三方应用服务器返回响应给 TOS,示例如下:

HTTP/1.1 200 OK
Date: Fri, 1 Jul 2022 01:00:36 GMT
Content-Length: 15
Content-Type: application/json

{"Status":"OK"}

返回上传回调结果

PutObject 请求返回结果

HTTP/1.1 200 OK
x-tos-id-2: 367be10900210004-a444ed0
x-tos-request-id: 367be10900210004-a444ed0
Date: Fri, 30 Jul 2021 08:05:36 GMT
server: TosServer
Content-Length: 15
Content-Type: application/json
ETag: 1c06e540e11d65a51aeb724e72fa641a

{"Status":"OK"}

CompleteMultipartUpload 请求返回结果

HTTP/1.1 200 OK
x-tos-id-2: 9b84750a5bbc0029-a444ed0
x-tos-request-id: 9b84750a5bbc0029-a444ed0
Date: Fri, 30 Jul 2021 13:59:38 GMT
server: TosServer
Content-Length: 15
Content-Type: application/json
Location: http://bucketname.tos-cn-beijing.volces.com/objectname
ETag: 7de47c292287f7965357c1ddd724b2b7-1

{"Status":"OK"}

注意

  • CompleteMultipartUpload 返回结果本身中存在消息体,使用上传回调功能后会覆盖原有的消息体,客户端需要对这种情况做好判断处理。

  • 当使用上传回调功能时,会新增 Location 头域用于返回新创建对象的带域名的 URL,以及 ETag 头域用于返回 ETag 值。

PostObject 请求返回结果

HTTP/1.1 200  OK
x-tos-id-2: 367be10900210004-a444ed0
x-tos-request-id: 367be10900210004-a444ed0
Date: Fri, 1 Jul 2022 01:00:36 GMT
Server: TosServer
Content-Length: 15
Content-Type: application/json
ETag: ab7abb0da4bca5323ab6119bb5dcd296
Location: http://bucketname.tos-cn-beijing.volces.com/objectname

{"Status":"OK"}

注意

PostObject 使用上传回调功能后会返回消息体,因此 HTTP 状态码会从 204 转为 200,客户端需要对这种情况做好判断处理。

当出现 CallbackFailed 错误码时,对应的 HTTP 状态码为 203,客户端需要对这种情况做好判断处理,其他状态码具体信息,请参见响应码