返回数据说明_API_Object Storage-文档中心

本文档详细解析对象存储服务的数据响应与回调机制系统，涵盖三大核心功能：

客户端响应控制（ReturnBody） - 通过动态变量（$(bucket), $(x:customVar)）定制直返客户端的数据格式，支持普通上传返回键值对、分片上传返回JSON
服务端回调协议（CallbackBody） - 配置HMAC-SHA1签名验证的异步回调，实现业务系统无缝对接
文件命名与预处理（SaveKey/PersistentOps） - 用时间戳/UUID等变量生成存储路径，配置音视频转码等自动化处理流水线

`returnBody` 返回机制

场景 1：返回由 `returnBody` 和 `returnUrl` 指定的请求 URL

例如：

    bucket:     image
    key:        205.jpg
    returnBody: bucket=$(bucket)&key=$(key)
    returnUrl:  http://www.abc.com

返回给上传者的内容是：

    http://www.abc.com?bucket=image&key=205.jpg&hash=610d0284a0923298247d3a269ee28908cdcc7476

场景 2：指定 `returnBody`，如果未指定 `returnUrl`，则返回 `returnBody` 指定的内容。

returnBody 便于自定义返回给客户端的信息。目前支持两种参数方法：自定义替换变量 和 指定替换变量。这两种方法可以任意组合使用。

注意：

对于普通上传，returnBody内容默认返回文件哈希值；对于分片上传，returnBody内容默认返回文件哈希值和key。

设置后，returnBody 返回的内容经过 URL 安全的 Base64 编码。为了更好说明，以下示例将显示解码后的内容。

自定义替换变量

格式： $(x:variable)
示例：

    ReturnBody: position=$(x:position)&message=$(x:message)
    Request Parameter: position=abc&message=Success

普通上传返回给上传者的内容是：

    position=abc&message=Success&hash=610d0284a0923298247d3a269ee28908cdcc7476

分片上传返回给上传者的内容是：

    {
        "position":"abc",
        "message":"Success",
        "key":"filename",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

注意：自定义变量必须是UTF-8格式，并且不能包含&，否则会被解析为乱码。

特殊替换变量

格式： $(variable)
示例：

    returnBody：url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

普通上传返回给上传者的内容是：

    url=http://abc.com/1.jpg&fsize=1231341&bucket=test&hash=610d0284a0923298247d3a269ee28908cdcc7476

分片上传返回给上传者的内容是：

    {
        "url":"http://abc.com/1.jpg",
        "fsize":"1231341",
        "bucket":"test",
        "key":"1.jpg",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

注意：指定参数的顺序是按这些参数值结果返回的顺序。

变量说明：

指定变量	描述	上传接口
$(persistentID)	上传预处理或触发持久化处理的过程ID。	普通上传（分片上传使用受限）
$(bucket)	获取上传目标空间名。	普通上传/分片上传
$(key)	获取保存在空间中的文件的资源名。	普通上传/分片上传
$(fname)	上传的原始文件名。	普通上传/分片上传
$(hash)	资源的Etag。	普通上传/分片上传
$(fsize)	资源大小，以字节为单位。	普通上传/分片上传
$(url)	访问资源的实际路径。	普通上传/分片上传
$(ip)	该请求的来源IP。	普通上传/分片上传
$(imageInfo)	上传图像的基本信息。	普通上传/分片上传
$(exif)	上传图像的exif信息。	普通上传/分片上传
$(avinfo)	视频元数据，JSON格式，经过URL安全的Base64编码。	普通上传/分片上传
$(mimeType)	资源类型，例如JPG图像的资源类型为image/jpg。	普通上传/分片上传

`callbackBody` 回调机制

callbackBody 适用于用户开启设置时自定义返回给客户端信息的格式，即回调服务器。

注意：回调内容通过URLEncode编码，回调服务器在接收到回调内容后可以进行相关解码

callbackBody 支持三种参数方法：常量、自定义替换变量、指定替换变量，可以任意组合使用。

回调数据说明

常量

格式： key1=value1&key2=value2
描述：对象存储平台获取到该常量参数后，将不进行任何处理，直接回调信息callbackUrl。
示例：

username=john&age=21

自定义替换变量

格式： $(x:variable)
示例：

    callbackBody: position=$(x:position)&message=$(x:message)

若 $(x:position)=abc, $(x:message)=Success，则返回给回调服务器的内容为：

    position%3dabc%26message%3dSuccess%0a%0a

注意：自定义变量必须是UTF-8格式，并且不能包含&，否则会被解析为乱码。

特殊替换变量

格式： $(variable)
示例：

    callbackBody: url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

返回给回调服务器的内容（经过urlencode编码）为：

    url%3daHR0cDovL2FiYy5jb20vMS5qcGc%3d%26fsize%3d1231341%26bucket%3dtest%0a

变量说明：

指定变量	描述	上传接口
$(persistentID)	上传预处理或触发持久化处理的过程ID。	普通上传（分片上传的受限使用）
$(bucket)	获取上传目标空间名。	普通上传/分片上传
$(key)	获取保存在空间中的文件的资源名。	普通上传/分片上传
$(fname)	上传的原始文件名	普通上传/分片上传
$(hash)	资源的Etag	普通上传/分片上传
$(fsize)	资源大小，以字节为单位。	普通上传/分片上传
$(mimeType)	资源类型，例如JPG图像的资源类型为image/jpg。	普通上传/分片上传
$(url)	访问资源的实际路径，URL安全的Base64编码。	普通上传/分片上传
$(ip)	该请求的来源IP。	普通上传/分片上传
$ (costTime)	从服务器接受请求到开始回调服务器的时间，以毫秒为单位。	普通上传/分片上传
$(avinfo)	视频元数据，JSON格式，经过URL安全的Base64编码。	普通上传/分片上传
$(imageInfo)	上传图像的基本信息，经过URL安全的Base64编码。	普通上传/分片上传
$(exif)	上传图像的exif信息，经过URL安全的Base64编码。	普通上传/分片上传

回调响应说明

在获取到回调服务器的响应代码和响应内容（必须是JSON格式）后，对象存储平台将根据回调服务器的响应代码和响应内容返回给客户端一个响应。

当回调服务器响应为200且返回的内容为json字符串时，对象存储平台返回给客户端的响应代码为200，响应内容是：

    {
      "hash": "<hash string>",
      "response": "<response string>"
    }

当回调服务器响应异常时，对象存储平台返回给客户端的响应代码为579，响应内容是：

    {
      "hash": "<hash string>",
      "error": {
        "callbackUrl": "<callbackUrl string>",
        "callback_bodyType": "<callback_bodyType string>",
        "callback_body": "<callback_body string>",
        "token": "<token string>",
        "err_code": "<err_code string>",
        "error": "<unexpected response>"
      }
    }

回调安全机制

CDNetworks 对象存储将在回调请求头中添加 Authorization 字段。

格式：

    <Accesskey>:<Urlsafe_Base64_Encode(hmac_sha1(callBackUrlWithQuery+"\n"+urlsafe_base64_encode(callbackBody),SecretKey))>

示例：

    d0e56f9f4a75267eba123348f839fbedcd9464c6:OTQzNzU5YWVjOTZlNTRlMWIwYmQzZTA2ZDhjMTFhOWEyNGM1ZjIzZg==

回调重试机制

当上传回调失败时，默认连续重试3次，然后每隔1分钟重试一次（共5次），总共重试8次。

如果重试后回调成功，则正常回调响应将返回状态码200。
如果重试后回调服务器仍未返回正常响应，则异常回调响应将返回状态码579。

`saveKey` 自定义命名

saveKey 用于资源名自定义，仅在用户上传的 scope 没有指定 key 时生效。此字段仅支持单文件普通上传。
saveKey 支持三种参数方法：常量、自定义替换变量、指定替换变量，可以任意组合使用。

资源名称说明

常量

格式： value
描述：指定常量参数后，对象存储不会进行任何处理，信息将直接用于命名。
示例：

    saveKey: constant

格式： dirnamr/key
描述：对象存储没有多级文件目录的概念，但可以通过文件名实现虚拟化路径文件。
示例：

    saveKey: dir/key

自定义替换变量

格式： $(x:variable)
示例：

    saveKey: $(x:position)

如果 $(x:position)= test，文件上传到对象存储后将命名为 test

注意：自定义变量必须是UTF-8格式，并且不能包含&，否则会被解析为乱码。

特殊替换变量

格式： $(variable)
示例：

    saveKey: $(year)/$(month)/$(hash)

如果当前时间是2016年4月，文件将上传到对象存储并保存为2016/04/文件的特定HASH值。

变量说明：

指定变量	描述
$(fname)	上传的原始文件名
$(hash)	资源的Etag
$(mimeType)	资源类型，例如JPG图像的资源类型为image/jpg。
$(suffix)	资源的后缀名，从原文件的后缀中获取。如果原文件没有后缀，则默认为unknown
$(fprefix)	资源的原始文件名（不包括后缀部分）
$(uuid)	随机数
$(year)	上传时间的年份。例如：2015
$(month)	上传时间的月份。例如：01
$(day)	上传时间的日期。例如：01
$(hour)	上传时间的小时。例如：01
$ (min)	上传时间的分钟。例如：01
$(sec)	上传时间的秒。例如：01

转码指令说明

视频转码和截图等指令请参考 Ops参数格式。
示例：

视频转码：

    persistentOps=avthumb/mp4/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=;avthumb/flv/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=

视频截图：

    persistentOps=vframe/jpg/offset/10|saveas/YnVja2V0OmZpbGVrZXk=;vframe/jpg/offset/15|saveas/YnVja2V0OmZpbGVrZXk=

注意：指令可以组合，多个指令可以用 ; 拼接。

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

返回数据说明

`returnBody` 返回机制

场景 1：返回由 `returnBody` 和 `returnUrl` 指定的请求 URL

场景 2：指定 `returnBody`，如果未指定 `returnUrl`，则返回 `returnBody` 指定的内容。

`callbackBody` 回调机制

回调数据说明

回调响应说明

回调安全机制

回调重试机制

`saveKey` 自定义命名

资源名称说明

转码指令说明

目录

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

返回数据说明

returnBody 返回机制

场景 1： 返回由 returnBody 和 returnUrl 指定的请求 URL

场景 2： 指定 returnBody，如果未指定 returnUrl，则返回 returnBody 指定的内容。

callbackBody 回调机制

回调数据说明

回调响应说明

回调安全机制

回调重试机制

saveKey 自定义命名

资源名称说明

转码指令说明

目录

`returnBody` 返回机制

场景 1：返回由 `returnBody` 和 `returnUrl` 指定的请求 URL

场景 2：指定 `returnBody`，如果未指定 `returnUrl`，则返回 `returnBody` 指定的内容。

`callbackBody` 回调机制

`saveKey` 自定义命名