上传回调

更新时间：2024-04-16

上传同步回调

接口描述

此接口用于BOS在上传文件（Object）时提供同步回调（Callback）给应用服务器。应用服务器指的是用户提供的回调地址对应的服务器。

支持的上传类操作如下：

普通上传（PutObject）
完成分片上传（CompleteMultipartUpload）

请求语法（Request）

PUT /<ObjectName> HTTP/1.1
Host: <BucketName>.bj.bcebos.com
Date: <Date>
Authorization: <AuthorizationString>
Content-Type: text/plain
Content-Length: <Content_Length>
x-bce-process: <callback_command>

请求参数
见"请求头域"部分说明。
请求头域

名称	类型	描述	是否必须
x-bce-process	string	使用x-bce-process参数存储回调的命令，命令有两种形式，一是附在querystring中，二是附在header中。具体使用见下文的"x-bce-process使用说明"部分。	否

x-bce-process命令的形式

x-bce-process: callback/callback,${key}_${value},${key}_${value}

x-bce-process参数说明：

参数名称	缩写	类型	取值范围	描述	是否必选
urls	u	string	-	经过url安全的Base64编码后的地址列表，最多3个地址，具体内容为json数组`["http://test1.com/callback", "http://test2.com/callback"]`	是
mode	m	string	`sync`	当前只能为同步。不设置时默认为`sync`	否
vars	v	string	-	任意自定义参数，回调时透传，长度不超过1024字节,建议数据进行base64编码。	否
encrypt	e	string	`config`	回调签名的加密类型。可取值如下： `config`：表示通过创建事件通知规则配置了回调请求的签名密钥。	否
key	k	string	-	回调签名的key，可取值如下：如果encrypt为"config"，表示通过创建事件通知规则配置了回调请求的签名密钥，值为对应的事件通知规则的id。	否

x-bce-process使用说明:

x-bce-process回调用的子命令为callback，参数使用缩写;
如果用户在一次请求中提供了多条url回调地址，当第一次回调成功则停止并返回，后续url不再做回调。
回调的信息放在JSON Body中返回。
参数"encrypt"、"key"只在需要设置回调签名的时候使用。具体见下文介绍。

响应（response）

响应元素

响应元素同PutObject、CompleteMultipartUpload 接口的响应元素。

如果同步回调成功且用户的应用回调服务器有响应内容，响应元素增加"callback"字段来存储应用服务器响应内容，并返回客户端。

名称	类型	描述
callback	object	包含用户应用服务器返回内容的对象
+result	string	用户应用服务器的返回内容

回调说明:

用户应用服务器返回StatusCode: 200响应认为是回调成功并结束，对于其他错误或不响应，则重试下一个url。
如果所有url的回调都失败，则回调失败，同时返回错误码Status Code: 203，表示文件已经成功上传到了BOS，但回调失败。回调失败只是表示BOS没有收到预期的回调响应，不代表应用服务器没有收到回调请求。
回调成功时，应用服务器的返回值不能超过1MB，否则认为回调失败，错误信息为"PayloadTooLarge"。
对于CompleteMultipartUpload原有接口就有响应Body的情况，callbackResult会附加到原有返回的JSON中。
回调失败时，code和message中会附带失败的原因。

回调请求格式

上传同步回调应用服务的请求格式与bucket事件通知的回调格式一致。

例如,用户计划回调的地址为["https://www.test.com/callback"]，经过base64编码后的取值为"WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd"。用户计划携带自定义参数内容为{"key1":"value1"},经过base64编码后为"eyJrZXkxIjoidmFsdWUxIn0=".

假设用户上传请求时header中携带了如下回调命令：

x-bce-process: callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd,v_eyJrZXkxIjoidmFsdWUxIn0=

则向用户应用服务器发起url回调请求示例如下所示，其中签名"Authorization"是可选的。

POST /<callback_url> HTTP/1.1
Host: <User_Host>
Date: <Date>
Content-Type: application/json; charset=utf-8
Authorization: <AuthorizationString>
Content-Length: <Content_Length>
{
    "events": [
        {
            "version": "1.0",
            "eventId": "2a513199-bbb9-4ac7-b12a-60213c26810d",
            "eventOrigin": "bos:callback",
            "eventTime": "2023-09-05T02:28:49Z",
            "eventSource": "bos:callback",
            "eventType": "PutObject",
            "eventFrom": "Client",
            "content": {
                "userId": "abcdefgh12345678a4ffa3b2ececa17f",
                "ownerId": "abcdefgh12345678a4ffa3b2ececa17f",
                "accessKeyId": "*****************************",
                "domain": "bj.bcebos.com",
                "bucket": "bucket-test",
                "object": "object-test",
                "etag": "977b9623a15e520c663ac5ff6647e881",
                "contentType": "application/octet-stream",
                "filesize": 24414,
                "lastModified": "2018-09-05T02:28:49Z",
                "storageClass": "STANDARD",
                "xVars": "eyJrZXkxIjoidmFsdWUxIn0="
            }
        }
    ]
}

回调签名（可选）

用户设置x-bce-process同步请求回调参数之后，BOS服务端将会按照用户设置的回调URL发送POST回调请求给用户的应用服务器。应用服务器收到回调请求之后，如果希望验证回调请求确实是由BOS发起的话，可以通过在回调中带上签名来验证BOS的身份。

回调安全使用百度智能云的IAM签名算法来实现，具体可参考IAM签名算法。

签名过程分为三步：

（1）提前通过创建事件通知规则设置密钥。用户可以在通过控制台或者sdk创建。

例如创建事件通知规则的id为"callback1"，其中key为用户设置密钥，长度为32字符，可取值为数字[0-9]和小写英文字母。

PUT /?notification HTTP/1.1
Host: <BucketName>.bj.bcebos.com
Date: <Date>
Authorization: <Authorization_String>
Content-Type: application/json; charset=utf-8
Content-Length: <Content_Length>
{
    "notifications": [
        {
            "id": "callback1",
            "encryption": {
                "key": "12345678abcdefgh9d1aff8bc436a2f6"
            }
        }
    ]
}

（2）上传文件请求中，携带含加密参数的回调命令。例如用户计划回调的地址为["https://www.test.com/callback"]，经过base64编码后的取值为"WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd"。

x-bce-process: callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd,e_config,k_callback1,

（3）BOS服务端向用户的应用服务器发起带签名的回调。其中计算签名的AK为用户本次请求的AK(如果没有带签名，默认使用"-")，SK为用户在第一步中设置的密钥。生成的签名位于请求头"Authorization"中。

示例

请求示例
例如用户计划回调的地址为["https://www.test.com/callback"]，经过base64编码后的取值为"WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd"。

附在Header中：

PUT /<ObjectName> HTTP/1.1
Host: <BucketName>.bj.bcebos.com
Date: <Date>
Authorization: <AuthorizationString>
Content-Type: text/plain
Content-Length: <Content_Length>
x-bce-process: callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd

附在query中：

http://<BucketName>.bj.bcebos.com/image.png?x-bce-process=callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd

PutObject响应示例

回调完成后，将回调的结果附带返回给客户端，其格式如下所示：

HTTP/1.1 200 OK
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 22
Connection: close
Server: BceBos
{
    "callback": {
        "result": "${callback_result}"
    }
}

CompleteMultipartUpload响应示例

HTTP/1.1 200 OK
x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Connection: close
Server: BceBos
{
	"location":"http://bj.bcebos.com/BucketName/ObjectName",
	"bucket":"BucketName",
	"key":"object",
	"eTag":"3858f62230ac3c915f300c664312c11f",
    "callback": {
        "result": "${callback_result}"
    }
}

音视频处理接口

SDK

百度智能云

对象存储 BOS