You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

上传回调

最近更新时间：2024.03.07 11:24:53

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

我的收藏

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

上传回调说明

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

上传回调的流程如下：
图片

上传回调构造参数

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

回调参数

回调参数是一段经过 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" : "bucket-test", "size" : 1024}。

变量名

变量说明

变量类型

bucket

上传的桶名。

string

key

上传的对象名。

string

object

上传的对象名。

string

size

上传对象的大小。

int64

etag

上传后对象的 ETag。

string

crc64ecma

上传后对象的 CRC64。

string

versionId

上传后对象的版本号，只在桶开启了多版本特性时有值。

string

filename

PostObject 上传的文件原名。

string

fname

PostObject 上传的文件原名。

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，客户端需要对这种情况做好判断处理，其他状态码具体信息，请参见响应码。