对象存储 Callback

在上传对象到 COS 的请求中携带 Callback 参数可以实现上传回调。本接口白名单开放，如需使用 Callback，请 联系我们 开通白名单。
注意：
仅 PutObject、PostObject、CompleteMultipartUpload 接口支持 Callback。
功能说明
通过上传回调，当用户上传对象到 COS 后，COS 不会立即返回上传结果给用户，而是将相关信息发送给用户的回调服务器，待回调服务器返回回调结果后，再和上传结果一起返回给用户。
上传回调的流程如下：
﻿
﻿
﻿
回调步骤
步骤1：构造回调参数
COS 接收到上传请求后，若携带了回调参数，则会发起回调请求。关于回调的参数有两个：
回调参数 callback 
自定义变量参数 callback-var（可选）
一、回调参数 callback
callback 参数字段说明
回调参数 Callback 是一个经过 Base64 编码的 JSON 字符串，包括四个字段，详情如下。
字段
说明
是否必选
callbackUrl
对象上传成功后，COS 向此 URL 发送回调请求，请求方法为 POST，body为 callbackBody 指定的内容。
如果未配置或者配置值为空则不发起上传回调。
支持配置多个URL，最多不超过5个URL，多个URL间以分号（;）分隔。COS 会依次发送请求直到第一个返回成功为止。
支持填写 HTTP/HTTPS，若未填写，默认发送 HTTP。
为了保证正确处理中文等情况，callbackUrl 需做URL编码处理，例如 http://example.com/测试.php?key=value&名称=值，URL 编码后为：http://example.com/%E6%B5%8B%E8%AF%95.php?key=value&%E5%90%8D%E7%A7%B0=%E5%80%BC。
是
callbackHost
发起回调请求时 Host 头的值，需要符合域名和 IP 规则。
如果没有配置 callbackHost，则会解析 callbackUrl 中的 URL 并将解析出的 Host 填充到callbackHost 中。
否
callbackBody
发起回调时请求 body 的值，形如 key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123或{"key":${object},"etag":${etag},"my_var"=${x:my_var},"my_var1":123}
支持填入三类变量：系统变量、自定义变量和常量，详细信息见 callbackBody 说明。
是
callbackBodyType
回调请求的 Content-Type，支持 application/x-www-form-urlencoded 和 application/json，默认为前者。
callbackBodyType 的取值为 application/x-www-form-urlencoded，则 callbackBody 中的变量将会按照字符串格式替换。
如果为 application/json，则会按照 JSON 格式替换其中的变量。
否
callback 参数示例
callbackBodyType 为 application/json 的 callback 参数的示例如下：
{
"callbackUrl":"https://14.215.XX.XX/callback.php",
"callbackHost":"14.215.XX.XX",
"callbackBody":"{\\"key\\":${object},\\"etag\\":${etag},\\"my_var\\"=${x:my_var},\\"my_var1\\":123}",
"callbackBodyType":"application/json"
}
 callbackBodyType 为 application/x-www-form-urlencoded 的 callback 参数的示例如下：
{
"callbackUrl":"https://14.215.XX.XX/callback.php",
"callbackBody":"key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123"
}
callbackBody 说明
回调请求的 body 值，支持填入三类变量：系统变量、自定义变量和常量。
若 callbackBodyType 为 application/json，则 callbackBody 示例如下：
"{\\"key\\":${object},\\"etag\\":${etag},\\"my_var\\"=${x:my_var},\\"my_var1\\":123}"
若 callbackBodyType 为 application/x-www-form-urlencoded，则 callbackBody 形如key1=value1&key2=value2&key1=value1，示例如下：
"key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123"
系统变量
示例中，key=${object}和&etag=${etag}为系统变量。
针对系统变量，COS 会自动读取 COS 相关的系统参数（如存储桶名称 bucket、对象名 object 等）替换变量(如${bucket}、${object})填入 body 中，发送给回调服务器，COS 支持的系统变量如下表所示。
其中，使用 exif、imageInfo、videoInfo 变量时，需要注意以下几点：
这三类变量仅支持在国内公有云地域使用。
获取这三类变量依赖数据万象（Cloud Infinite，CI）服务的能力。用户需要开通 CI 服务，并保证 COS 服务角色有权调用 CI 服务。获取这三类变量，会由CI 服务收取相应的费用，详情可参考 数据万象计费概述。
支持子变量，例如${变量名.子变量}、${变量名.二级子变量}。并且，为了避免 callbackBody 携带的内容太多，影响接口性能，不支持直接填写${imageInfo}，必须写明具体的子变量。
变量支持的具体子变量，可参考数据万象和媒体处理服务的产品文档：获取图片 EXIF、获取图片基本信息 imageInfo、获取媒体信息 videoinfo。
注意：
exif、imageInfo 变量仅支持图片文件，videoInfo 仅支持音视频文件，格式不符将导致回调失败（错误码 203）。
系统变量
说明
是否必选
bucket
存储桶名称，形如 <bucket-appid>
否
region
存储桶地域，如 ap-beijing
否
object
对象名
否
size
对象大小
否
mimeType
资源类型，例如 jpeg 图片的资源类型为 image/jpeg，以用户上传的 Content-Type 为准
否
exif
如果上传的对象为图片类型，支持查看图片的 exif 信息，变量填写格式为 ${exif.xxx}。
否
videoInfo
如果上传的对象为音视频类型，支持查看音视频资源的元信息。变量填写格式为 ${videoInfo.xxx}。
否
imageInfo
如果上传的对象为图片类型，支持查看图片的基本信息，变量填写格式为 ${imageInfo.xxx}。
否
自定义变量
示例中，my_var=${x:my_var}为自定义变量，变量必须以小写的x:开头。
针对 PostObject 请求，用户需要将 ${x:my_var} 等自定义变量的值附加在表单域中，若存在多个自定义变量，则分别使用单独的表单域。COS 会从表单域中提取变量值填入 body 中，发送给回调服务器。
常量
示例中，my_var1=123是常量，回调请求的 body 中会保持原先的值。
二、自定义变量参数 callback-var（可选）
对于上文所提到的 callbackBody 的自定义变量，用户可以通过 callback-var 参数来配置自定义参数。自定义参数是一个 Key-Value 的Map，用户可以配置自己需要的参数到该 Map。自定义参数的 Key-Value 的 Map 示例如下，Key 必须以小写的x:开头。
callback-var{
    "x:my_var":"value1"
}
在 COS 发起 POST 回调请求的时候，会将自定义参数、系统参数的值提取出来，放在 body 中发送给回调服务器，下面给出一个示例。
假设上传对象名为a.txt，etag 为 e7df7cd2ca07f4f1ab415d457a6e1c13 ，用户上传请求中 callbackBody为：
key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123
经过替换，COS 发送的 Post 回调请求的 body为：
key=a.txt&etag=e7df7cd2ca07f4f1ab415d457a6e1c13&my_var=value1&my_var1=123
步骤2：发起带回调参数的上传请求（用户 > COS）
在 PutObject、PostObject、CompleteMultipartUpload 接口中携带回调参数 callback 和 自定义回调参数 callback-var，需要对上述构造的 JSON 字符串进行 base64 编码，然后附加到请求中。
接口
回调参数 callback
自定义回调参数 callback-var
PostObject
表单字段 x-cos-callback
表单字段 x-cos-callback-var
PutObject
请求头部 x-cos-callback
请求头部 x-cos-callback-var
CompleteMultipartUpload
请求头部 x-cos-callback
请求头部 x-cos-callback-var
1. PostObject 请求
在 PostObject 请求的 body 中使用表单域携带 x-cos-callback 参数和 自定义参数。
首先，将上文构造的 callback 参数 的 JSON 字符串进行 base64 编码。在 Post 上传时，将 callback 参数附加在单独的表单域中，示例如下。
JSON 字符串的 callback 参数：
{
"callbackUrl":"https://14.215.XX.XX/callback.php",
"callbackHost":"14.215.XX.XX",
"callbackUrl":"https://14.215.XX.XX/callback.php",
"callbackBody":"key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123"
}
经过 base64 编码后，附加在表单域中：
--9431149156168
Content-Disposition: form-data; name="x-cos-callback"
eyJjYWxsYmFja1VybCI6ICIxNC4yMTUuMTEuMTEvY2FsbGJhY2sucGhwIiwgImNhbGxiYWNrSG9zdCI6ICIxNC4yMTUuMTEuMTEiLCAiY2FsbGJhY2tCb2R5IjogImtleT0ke29iamVjdH0mZXRhZz0ke2V0YWd9Jm15X3Zhcj0ke3g6bXlfdmFyfSZteV92YXIxPTEyMyIsICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9
如果 callbackBody 中使用了自定义变量，不能直接将自定义变量参数 callback-var直接附加到表单域中，每个自定义的参数都需要使用独立的表单域来附加。例如，自定义参数 JSON 字段如下：
callback-var{
    "x:my_var":"value1"
}
那么 PostObject 请求的完整表单域为：
--9431149156168
Content-Disposition: form-data; name="x-cos-callback"
eyJjYWxsYmFja1VybCI6ICIxNC4yMTUuMTEuMTEvY2FsbGJhY2sucGhwIiwgImNhbGxiYWNrSG9zdCI6ICIxNC4yMTUuMTEuMTEiLCAiY2FsbGJhY2tCb2R5IjogImtleT0ke29iamVjdH0mZXRhZz0ke2V0YWd9Jm15X3Zhcj0ke3g6bXlfdmFyfSZteV92YXIxPTEyMyIsICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9
--9431149156168
Content-Disposition: form-data; name="x:my_var"
value1
COS 支持在 Post 请求的 Policy 中添加 callback 字段，在验证签名对 callback 字段进行校验。例如，
{
"expiration": "2019-08-30T09:38:12.414Z",
"conditions": [
{ "x-cos-callback": "eyJjYWxsYmFja1VybCI6ICIxNC4yMTUuMTEuMTEvY2FsbGJhY2sucGhwIiwgImNhbGxiYWNrSG9zdCI6ICIxNC4yMTUuMTEuMTEiLCAiY2FsbGJhY2tCb2R5IjogImtleT0ke29iamVjdH0mZXRhZz0ke2V0YWd9Jm15X3Zhcj0ke3g6bXlfdmFyfSZteV92YXIxPTEyMyIsICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9"},
{ "acl": "default" },
{ "bucket": "examplebucket-1250000000" },
[ "starts-with", "$key", "a.txt" ],
[ "starts-with", "$Content-Type", "image/" ],
[ "eq", "$x-cos-server-side-encryption", "AES256" ],SIGN
{ "q-sign-algorithm": "sha1" },
{ "q-ak": "************************************" },
{ "q-sign-time": "1567150692;1567157892" }
]
}
2. PutObject 和 CompleteMultipartUpload 请求
在 PutObject 和 CompleteMultipartUpload 请求的请求头部 x-cos-callback 和 x-cos-callback-var 携带 base64 编码后的回调相关参数。
x-cos-callback base64 编码后的值可参考 PostObject 请求，x-cos-callback-var base64 编码过程如下。原始 json 字符串如下。
{"x:my_var": "value1"}
base64 编码后，字符串如下。
eyJ4Om15X3ZhciI6ICJ2YWx1ZTEifQ==
PutObject 请求示例
PUT /<ObjectKey> HTTP/1.1
x-cos-callback: eyJjYWxsYmFja1VybCI6ICIxNC4yMTUuMTEuMTEvY2FsbGJhY2sucGhwIiwgImNhbGxiYWNrSG9zdCI6ICIxNC4yMTUuMTEuMTEiLCAiY2FsbGJhY2tCb2R5IjogImtleT0ke29iamVjdH0mZXRhZz0ke2V0YWd9Jm15X3Zhcj0ke3g6bXlfdmFyfSZteV92YXIxPTEyMyIsICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9
x-cos-callback-var: eyJ4Om15X3ZhciI6ICJ2YWx1ZTEifQ==
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String
﻿
[Object Content]
CompleteMultipartUpload 请求示例
POST /<ObjectKey>?uploadId=UploadId HTTP/1.1
x-cos-callback: eyJjYWxsYmFja1VybCI6ICIxNC4yMTUuMTEuMTEvY2FsbGJhY2sucGhwIiwgImNhbGxiYWNrSG9zdCI6ICIxNC4yMTUuMTEuMTEiLCAiY2FsbGJhY2tCb2R5IjogImtleT0ke29iamVjdH0mZXRhZz0ke2V0YWd9Jm15X3Zhcj0ke3g6bXlfdmFyfSZteV92YXIxPTEyMyIsICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9
x-cos-callback-var: eyJ4Om15X3ZhciI6ICJ2YWx1ZTEifQ==
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: application/xml
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String
﻿
[Request Body]
步骤3：发起回调请求（COS > 回调服务器）
COS 接收到附加回调参数的上传请求后，根据 callback 和 callback-var 这两个参数构造回调请求，向回调服务器发起请求。
请求地址：callbackurl
请求方法：POST
请求体：callbackBody 指定的内容，但需要将系统变量、自定义变量的值进行替换，将变量转换为具体值。
向回调服务器发起的请求示例：
POST /callback.php HTTP/1.0
Host: 14.215.XX.XX
Connection: close
Content-Length: Content-Length
Content-Type: application/x-www-form-urlencoded
key=a.txt&etag=e7df7cd2ca07f4f1ab415d457a6e1c13&my_var=value1&my_var1=123
步骤4：回调身份验证（可选）
用户可以通过回调请求中的 Referer、User-Agent、x-cos-callback-auth 头部，证明回调请求确实为 COS 发起的。Referer 头部为 tencentcos.cn，User-Agent 头部为 tencentcos，x-cos-callback-encrypted-auth 用于验证回调请求的内容是否被篡改。
POST /callback.php?id=1&index=2 HTTP/1.0
Host: 14.215.XX.XX
Referer: tencentcos.cn
User-Agent: tencentcos
x-cos-callback-encypted-auth: Auth String
﻿
key=a.txt&etag=e7df7cd2ca07f4f1ab415d457a6e1c13&my_var=value1&my_var1=123
x-cos-callback-encypted-auth 的生成
白名单用户请联系我们设置一个客户指定密钥 ckey，COS 将使用客户指定密钥 ckey 对回调请求的内容进行对称加密。
第一步，生成加密明文。
sign_str = url_decode(path) + query_string + ‘\\n’ + body
sha_sign_str = sha1(sign_str)
其中 path 为回调请求的路径，query_string 为回调请求的参考，body 为回调请求的请求体。例如，path 为 /index.php ，query_string 为 ?id=1&index=2 ，body 为 bucket=yonghu-test
第二步，生成加密密文。
x-cos-callback-encrypted-auth = base64(HMAC-SHA1(sha_sign_str,ckey))
第三步，验证签名。客户回调服务端接收到回调请求后，使用对称密钥 ckey 重复以上加密过程，和回调签名的内容进行对比，即可验证请求是否被篡改过。
步骤5：返回回调结果（回调服务器 > COS）
用户的回调服务器接收到 COS 的回调请求，验证回调身份、构造请求返回。
回调服务器返回的响应，应当为 HTTP/1.1 200 OK ，body 必须为 JSON 格式，响应头 Content-Length 必须为合法的值，且大小不超过 3 MB。例如：
HTTP/1.0 200 OK
Server: User Server
Date: Date
Content-Type: Content-Type
Content-Length: 9
{"a":"b"}
步骤6：返回上传结果（COS > 用户）
对于 PostObject 和 PutObject 请求，如果上传成功、回调成功，回调服务器响应的 json body，会原样作为上传请求的 body 返回，例如：
HTTP/1.1 200 OK
Date: 
Content-Type: application/json
Content-Length: 
Connection: keep-alive
ETag: "e7df7cd2ca07f4f1ab415d457a6e1c13"
x-cos-request-id: 55F6BF87207FB30F2640C***
{"a":"b"}
上传成功、回调失败，会返回 203 错误码，并通过 xml 格式返回CallbackFailed 错误码和相应的错误信息。
HTTP/1.1 203 Non-Authoritative Information 
﻿
<Error>
    <Code>CallbackFailed</Code>
    <Message>Error Status: 403 from callback server, should return 200 OK. </Message>
</Error>
对于 CompleteMultipartUpload 请求，由于请求本身求本身返回了 xml 请求体，其中包含了分块上传的相关的重要信息。因此，Callback 相关信息（对象信息、Callback 是否成功等）会被放在 XML 字段 CallbackResult 中，返回给客户。
上传成功、回调成功，Status 为 200 并返回 CallbackBody 字段。
上传成功、回调失败，Status 为 203 并返回 Error、Code、Message 字段。
CallbackResult 节点说明如下：
节点名称（关键字）
父节点
描述
类型
CallbackResult
CompleteMultipartUploadResult
Callback 的结果。
Container
Status
CompleteMultipartUploadResult.CallbackBodyResult
Callback 是否成功。枚举值，支持 200、203。200表示上传成功、回调成功；203表示上传成功，回调失败。
Integer
Error
CompleteMultipartUploadResult.CallbackResult
Status为203时，说明Callback，返回 Error，说明回调失败信息。
Container
Code
CompleteMultipartUploadResult.CallbackResult
回调失败信息的错误码，例如CallbackFailed
String
Message
CompleteMultipartUploadResult.CallbackResult
Callback 失败的错误信息。
String
CallbackBody
CompleteMultipartUploadResult.CallbackResult
Status为200时，说明上传成功、回调成功，返回 CallbackBody。内容为 CallbackBody 的 json 字符串base64编码后的字符串。
String
响应示例如下：
HTTP/1.1 200 OK
Content-Type: application/xml
﻿
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>"aa259a62513358f69e98e72e59856d88-3"</ETag>
    <CallbackResult>
        <Status>200|203</Status>
        <!--Status为203时，说明上传成功回调失败，返回 Error-->
        <Error>
            <Code>CallbackFailed</Code>
            <Message>Invalid callback param.</Message>
        </Error>
        <!--Status为200时，说明上传成功、回调成功，返回 Reponse，为客户回调服务器返回的json字符串base64编码后的结果。-->
        <CallbackBody>
            eyJhIjogImIifQ==
        </CallbackBody>
    </CallbackResult>
</CompleteMultipartUploadResult>
报错说明
若回调失败，上传成功，则返回 203 Non-Authoritative Information。错误码 CallbackFailed，Message 中返回回调失败的原因。例如：
HTTP/1.1 203 Non-Authoritative Information 
﻿
<Error>
    <Code>CallbackFailed</Code>
    <Message>Error Status: 403 from callback server, should return 200 OK. </Message>
</Error>
203 报错包含以下几种情况：
错误原因
Code
Message
用户的回调参数不合法
CallbackFailed
Invalid callback param.
调用数据万象服务，由于访问无权限、未开通服务等原因导致系统变量的参数获取失败。
CallbackFailed
Error status from ci: ${code}, should return 200 OK.
其中，${code}为数据服务返回的错误码，例如 400、403等。
回调服务器响应非200
CallbackFailed
Error status: XXX from callback server, should return 200 OK.
回调服务器响应体不是 JSON 格式
CallbackFailed
Response body is not valid json format.
SDK 使用示例
Android SDK获取回调结果
1. 上传文件并通过 setRequestHeaders 配置回调参数，更多上传文件的介绍请参考 上传对象。
// 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
        transferConfig);
﻿
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.txt"; //对象在存储桶中的位置标识符，即称对象键
String srcPath = new File(context.getCacheDir(), "exampleobject.txt")
        .toString(); //本地文件的绝对路径
//若存在初始化分块上传的 UploadId，则赋值对应的 uploadId 值用于续传；否则，赋值 null
String uploadId = null;
﻿
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, srcPath);
String callbackJson = "{ \\"callbackUrl\\": \\"https://14.215.XX.XX/callback.php\\", " +
        "\\"callbackHost\\": \\"14.215.XX.XX\\", " +
        "\\"callbackBody\\": \\"{\\"key\\":${object},\\"etag\\":${etag},\\"my_var\\"=${x:my_var},\\"my_var1\\":123}\\", " +
        "\\"callbackBodyType\\": \\"application/json\\" }";
String callbackBase64 = DigestUtils.getBase64(callbackJson);
// 配置回调参数
putObjectRequest.setRequestHeaders("x-cos-callback", callbackBase64, false);
// 上传文件
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(putObjectRequest, uploadId);
2. 设置成功回调，在回调中获取 callbackResult，如下面代码示例。
//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
 @Override
 public void onSuccess(CosXmlRequest request, CosXmlResult result) {
     COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
             (COSXMLUploadTask.COSXMLUploadTaskResult) result;
     // 获取 回调数据
     CallbackResult callbackResult = uploadResult.callbackResult;
     if(callbackResult != null){
         // 获取回调状态：Callback 是否成功。枚举值，支持 200、203。200表示上传成功、回调成功；203表示上传成功，回调失败。
         String status = callbackResult.status;
         if("200".equals(status)){
             // 获取回调内容 CallbackBody
             String callbackBody = callbackResult.getCallbackBody();
         } else if("203".equals(status)){
             // 获取回调状态：Status为203时，说明Callback，返回 Error，说明回调失败信息。
             callbackResult.error;
         }
     }
 }
});
iOS SDK获取回调结果
1. 上传文件并通过 setRequestHeaders 配置回调参数，更多上传文件的介绍请参考 上传对象。
QCloudCOSXMLUploadObjectRequest *request = [QCloudCOSXMLUploadObjectRequest new];
request.body = [NSURL fileURLWithPath:@"本地文件路径"];
request.object = @"examplebucket-1250000000";
request.regionName = @"ap-shanghai";
﻿
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
request.bucket = @"exampleobject.txt";
NSDictionary * dic = @{@"callbackUrl":@"http://127.0.0.0/index",@"callbackHost":@"127.0.0.0",@"callbackBody":@"bucket=${bucket}&object=${object}&etag=${etag}&test=test_123",@"callbackBodyType":@"application/json"};
NSData *data = [[dic qcloud_modelToJSONString] dataUsingEncoding:NSUTF8StringEncoding];
NSString *base64String = [data base64EncodedStringWithOptions:0];
﻿
// 配置回调参数
request.customHeaders = @{@"x-cos-callback":base64String}.mutableCopy;
[request setFinishBlock:^(QCloudUploadObjectResult *result, NSError *error) {
    //设置返回结果回调
}];
// 上传文件
[[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];
2. 设置成功回调，在回调中获取 callbackResult，如下面代码示例。
//设置返回结果回调
[request setFinishBlock:^(QCloudUploadObjectResult *result, NSError *error) {
  if (result.CallbackResult) {
     if (result.CallbackResult.Status.integerValue == 200) {
         // 获取回调CallbackBody: result.CallbackResult.CallbackBody
     }else if (result.CallbackResult.Status.integerValue == 203){
         // 获取回调状态：Status为203时，标识上传成功，回调失败。Error:回调失败信息。
         // result.CallbackResult.Error
     }
 }
}];
JavaScript SDK获取回调结果
1. JavaScript SDK 需升级至 v1.8.3 或更新的版本。
2. 上传文件并通过 Callback 配置回调参数，更多上传文件的介绍请参考 上传对象。
3. 在上传完成回调中获取 CallbackError 或 CallbackBody。
const callback = {
  callbackUrl: 'http://xxx/callback',
  callbackHost: 'xxx',
  callbackBody: 'key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123',
  callbackBodyType: 'application/x-www-form-urlencoded',
};
const callbackVar = { 'x:my_var': 'value1' };
cos.uploadFile(
    {
      Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶，必须字段 */
      Region: 'COS_REGION',  /* 存储桶所在地域，例如ap-beijing，必须字段 */
      Key: '1.jpg',  /* 存储在桶里的对象键（例如1.jpg，a/b/test.txt），必须字段 */
      Body: fileObject, /* 必须，上传文件对象，可以是input[type="file"]标签选择本地文件后得到的file对象 */
      SliceSize: 1024 * 1024 * 5, // 大于5mb才进行分块上传
      Callback: COS.util.encodeBase64(JSON.stringify(callback)),
      // CallbackVar: COS.util.encodeBase64(JSON.stringify(callbackVar)),  // 可选参数
    },
    function (err, data) {
      if (err) {
        console.log('上传失败', err);
      } else {
        console.log('上传成功');
        if (data.CallbackError) {
          console.log('回调失败', data.CallbackError?.Code);
        } else {
          console.log('回调成功', data.CallbackBody);
        }
      }
    }
  );
Flutter SDK获取回调结果
1. Flutter SDK 需升级至 v1.1.5 或更新的版本。
2. 上传文件并通过在 upload 方法中增加 callbackParam 参数配置回调，更多上传文件的介绍请参考 上传对象。
3. 设置成功回调，在成功回调中获取 CallbackResult，如下面代码示例。
    // 存储桶所在地域简称，例如广州地区是 ap-guangzhou
    String region = "COS_REGION";
    // 创建 CosXmlServiceConfig 对象，根据需要修改默认的配置参数
    CosXmlServiceConfig serviceConfig = CosXmlServiceConfig(
        region: region,
        isHttps: true,
    );
    // 创建 TransferConfig 对象，根据需要修改默认的配置参数
    TransferConfig transferConfig = TransferConfig();
    // 注册默认 COS TransferManger
    await Cos().registerDefaultTransferManger(serviceConfig, transferConfig);
﻿
    // 获取 TransferManager
    CosTransferManger transferManager = Cos().getDefaultTransferManger();
    // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
    String bucket = "examplebucket-1250000000";
    String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
    String srcPath = "本地文件的绝对路径"; //本地文件的绝对路径
    //若存在初始化分块上传的 UploadId，则赋值对应的 uploadId 值用于续传；否则，赋值 null
    String? _uploadId;
    // 上传回调参数
    String callbackParam = "{ \\"callbackUrl\\": \\"http://xx.xx.xx.xx/index\\", " +
    "\\"callbackHost\\": \\"xx.xx.xx.xx\\", " +
    "\\"callbackBody\\": \\"bucket=\\${bucket}&object=\\${object}&etag=\\${etag}&test=test_123\\", " +
    "\\"callbackBodyType\\": \\"application/x-www-form-urlencoded\\" }";
﻿
    // 上传成功回调
    successCallBack(Map<String?, String?>? header, CosXmlResult? result) {
      // todo 上传成功后的逻辑
      // 获取上传回调数据
        CallbackResult? callbackResult = result?.callbackResult;
        if(callbackResult != null){
          // 获取回调状态：Callback 是否成功。枚举值，支持 200、203。200表示上传成功、回调成功；203表示上传成功，回调失败。
          int status = callbackResult.status;
          print(status);
          if(status == 200){
            // 获取回调内容 CallbackBody
            String? callbackBody = callbackResult.callbackBody;
            print(callbackBody);
          } else if(status == 203){
            // 获取回调状态：Status为203时，说明Callback，返回 Error，说明回调失败信息。
            CallbackResultError? error = callbackResult.error;
            print(error?.code);
            print(error?.message);
          }
        }
    }
    //上传失败回调
    failCallBack(clientException, serviceException) {
      // todo 上传失败后的逻辑
      if (clientException != null) {
        print(clientException);
      }
      if (serviceException != null) {
        print(serviceException);
      }
    }
    //上传进度回调
    progressCallBack(complete, target) {
      // todo Do something to update progress...
    }
    //初始化分块完成回调
    initMultipleUploadCallback(
        String bucket, String cosKey, String uploadId) {
      //用于下次续传上传的 uploadId
      _uploadId = uploadId;
    }
    //开始上传
    TransferTask transferTask = await transferManager.upload(bucket, cosPath,
        filePath: srcPath,
        uploadId: _uploadId,
        callbackParam: callbackParam,
        resultListener: ResultListener(successCallBack, failCallBack),
        stateCallback: stateCallback,
        progressCallBack: progressCallBack,
        initMultipleUploadCallback: initMultipleUploadCallback
    );
﻿

字段	说明	是否必选
callbackUrl	对象上传成功后，COS 向此 URL 发送回调请求，请求方法为 POST，body为 callbackBody 指定的内容。如果未配置或者配置值为空则不发起上传回调。支持配置多个URL，最多不超过5个URL，多个URL间以分号（;）分隔。COS 会依次发送请求直到第一个返回成功为止。支持填写 HTTP/HTTPS，若未填写，默认发送 HTTP。为了保证正确处理中文等情况，callbackUrl 需做URL编码处理，例如 `http://example.com/测试.php?key=value&名称=值`，URL 编码后为：`http://example.com/%E6%B5%8B%E8%AF%95.php?key=value&%E5%90%8D%E7%A7%B0=%E5%80%BC`。	是
callbackHost	发起回调请求时 Host 头的值，需要符合域名和 IP 规则。如果没有配置 callbackHost，则会解析 callbackUrl 中的 URL 并将解析出的 Host 填充到callbackHost 中。	否
callbackBody	发起回调时请求 body 的值，形如 `key=${object}&etag=${etag}&my_var=${x:my_var}&my_var1=123`或`{"key":${object},"etag":${etag},"my_var"=${x:my_var},"my_var1":123}` 支持填入三类变量：系统变量、自定义变量和常量，详细信息见 callbackBody 说明。	是
callbackBodyType	回调请求的 Content-Type，支持 `application/x-www-form-urlencoded` 和 `application/json`，默认为前者。 callbackBodyType 的取值为 `application/x-www-form-urlencoded`，则 callbackBody 中的变量将会按照字符串格式替换。如果为 `application/json`，则会按照 JSON 格式替换其中的变量。	否

系统变量	说明	是否必选
bucket	存储桶名称，形如 `<bucket-appid>`	否
region	存储桶地域，如 `ap-beijing`	否
object	对象名	否
size	对象大小	否
mimeType	资源类型，例如 jpeg 图片的资源类型为 image/jpeg，以用户上传的 Content-Type 为准	否
exif	如果上传的对象为图片类型，支持查看图片的 exif 信息，变量填写格式为 ${exif.xxx}。	否
videoInfo	如果上传的对象为音视频类型，支持查看音视频资源的元信息。变量填写格式为 ${videoInfo.xxx}。	否
imageInfo	如果上传的对象为图片类型，支持查看图片的基本信息，变量填写格式为 ${imageInfo.xxx}。	否

接口	回调参数 callback	自定义回调参数 callback-var
PostObject	表单字段 x-cos-callback	表单字段 x-cos-callback-var
PutObject	请求头部 x-cos-callback	请求头部 x-cos-callback-var
CompleteMultipartUpload	请求头部 x-cos-callback	请求头部 x-cos-callback-var

节点名称（关键字）	父节点	描述	类型
CallbackResult	CompleteMultipartUploadResult	Callback 的结果。	Container
Status	CompleteMultipartUploadResult.CallbackBodyResult	Callback 是否成功。枚举值，支持 200、203。200表示上传成功、回调成功；203表示上传成功，回调失败。	Integer
Error	CompleteMultipartUploadResult.CallbackResult	Status为203时，说明Callback，返回 Error，说明回调失败信息。	Container
Code	CompleteMultipartUploadResult.CallbackResult	回调失败信息的错误码，例如CallbackFailed	String
Message	CompleteMultipartUploadResult.CallbackResult	Callback 失败的错误信息。	String
CallbackBody	CompleteMultipartUploadResult.CallbackResult	Status为200时，说明上传成功、回调成功，返回 CallbackBody。内容为 CallbackBody 的 json 字符串base64编码后的字符串。	String

错误原因	Code	Message
用户的回调参数不合法	CallbackFailed	Invalid callback param.
调用数据万象服务，由于访问无权限、未开通服务等原因导致系统变量的参数获取失败。	CallbackFailed	Error status from ci: ${code}, should return 200 OK. 其中，${code}为数据服务返回的错误码，例如 400、403等。
回调服务器响应非200	CallbackFailed	Error status: XXX from callback server, should return 200 OK.
回调服务器响应体不是 JSON 格式	CallbackFailed	Response body is not valid json format.

Callback

本页目录：

功能说明

回调步骤

步骤1：构造回调参数

一、回调参数 callback

callback 参数字段说明

callback 参数示例

callbackBody 说明

二、自定义变量参数 callback-var（可选）

步骤2：发起带回调参数的上传请求（用户 > COS）

1. PostObject 请求

2. PutObject 和 CompleteMultipartUpload 请求

步骤3：发起回调请求（COS > 回调服务器）

步骤4：回调身份验证（可选）

x-cos-callback-encypted-auth 的生成

步骤5：返回回调结果（回调服务器 > COS）

步骤6：返回上传结果（COS > 用户）

报错说明

SDK 使用示例

Android SDK获取回调结果

iOS SDK获取回调结果

JavaScript SDK获取回调结果

Flutter SDK获取回调结果