返回数据说明
更新时间：2023-08-17 17:36:54
本章介绍不同上传模式下的返回数据说明
上传响应内容
- 场景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内容默认返回文件hash值；采用分片上传，returnBody内容默认返回文件hash值及key。
- 设置了
returnBody后返回的内容经过URL安全的Base64编码，为了更好说明，以下举例结果为经过解码的内容展示。
自定义替换变量
格式：$(x:variable)
范例：
returnBody: position=$(x:position)&message=$(x:message)
请求参数：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
bucekt=test
普通上传返回给上传端内容为：
url=http://abc.com/1.jpg&fsize=1231341&bucket=test&hash=610d0284a0923298247d3a269ee28908cdcc7476
分片上传返回给上传端内容为：
{
"url":"http://abc.com/1.jpg",
"fsize":"1231341",
"bucekt":"test",
"key":"1.jpg",
"hash":"610d0284a0923298247d3a269ee28908cdcc7476"
}
注：指定的参数顺序也就是返回这些参数值结果的顺序。
特殊变量说明
| 特殊变量 | 描述 | 上传接口 |
|---|---|---|
| $(persistentId) | 上传预处理或者触发持久化处理的进程ID。 | 普通上传（分片上传受限使用） |
| $(bucket) | 获得上传的目标空间名。 | 普通上传/分片上传 |
| $(key) | 获得文件保存在空间中的资源名。 | 普通上传/分片上传 |
| $(fname) | 上传的原始文件名。 | 普通上传/分片上传 |
| $(hash) | 资源的Etag。 | 普通上传/分片上传 |
| $(fsize) | 资源尺寸，单位为字节(Byte)。 | 普通上传/分片上传 |
| $(url) | 访问该资源的实际路径。 | 普通上传/分片上传 |
| $(ip) | 此次请求的来源IP。 | 普通上传/分片上传 |
| $(imageInfo) | 上传图片的基本信息。 | 普通上传/分片上传 |
| $(exif) | 上传图片的exif信息。 | 普通上传/分片上传 |
| $(avinfo) | 视频元信息，格式为Json，经过URL安全的Base64编码。 | 普通上传/分片上传 |
| $(mimeType) | 资源类型，比如JPG图片的资源类型为image/jpg。 | 普通上传/分片上传 |
回调方式数据说明
描述
callbackBody适用于在用户开启callbackUrl设置时，即回调服务器，定制返回给客户端的信息格式。
注：该回调内容经过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%26fisize%3d1231341%26bucket%3dtest%0a
特殊变量说明
| 特殊变量 | 描述 | 上传接口 |
|---|---|---|
| $(persistentId) | 上传预处理或者触发持久化处理的进程ID。 | 普通上传（分片上传受限使用） |
| $(bucket) | 获得上传的目标空间名。 | 普通上传/分片上传 |
| $(key) | 获得文件保存在空间中的资源名。 | 普通上传/分片上传 |
| $(fname) | 上传的原始文件名 | 普通上传。/分片上传 |
| $(hash) | 资源的Etag | 普通上传。/分片上传 |
| $(fsize) | 资源尺寸，单位为字节(Byte)。 | 普通上传/分片上传 |
| $(mimeType) | 资源类型，比如JPG图片的资源类型为image/jpg。 | 普通上传/分片上传 |
| $(url) | 访问该资源的实际路径，经过了URL安全的Base64编码。 | 普通上传/分片上传 |
| $(ip) | 此次请求的来源IP。 | 普通上传/分片上传 |
| $(costTime) | 服务器接受请求到开始回调回调服务器的时间，单位毫秒。 | 普通上传/分片上传 |
| $(avinfo) | 视频元信息，格式为JSON，经过了URL安全的Base64编码。 | 普通上传/分片上传 |
| $(imageInfo) | 上传图片的基本信息，经过了URL安全的Base64编码。 | 普通上传/分片上传 |
| $(exif) | 上传图片的exif信息，经过了URL安全的Base64编码。 | 普通上传/分片上传 |
| $(mimeType) | 资源类型，比如JPG图片的资源类型为image/jpg。 | 普通上传/分片上传 |
回调应答说明
在得到回调服务器的响应码和响应内容（必须是JSON格式）后，云存储平台会根据回调服务器的响应码和响应内容，向客户端返回应答。
1.回调服务器的应答为200且返回内容为json串时，云存储给用户端的响应码为200，响应内容为:
{
"hash": "<hash string>",
"response": "<response string>"
}
2.回调服务器应答异常时，云存储给用户端的响应码为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>"
}
}
回调安全机制
网宿云存储会在回调的请求头中，加入Authorization字段。
格式：
<Accesskey>:<Urlsafe_Base64_Encode(hmac_sha1(callBackUrlWithQuery+"\n"+urlsafe_base64_encode(callbackBody),SecretKey))>
范例：
d0e56f9f4a75267eba123348f839fbedcd9464c6:OTQzNzU5YWVjOTZlNTRlMWIwYmQzZTA2ZDhjMTFhOWEyNGM1ZjIzZg==
回调重试机制
上传回调失败时，默认连续重试3次。
- 如果重试后回调成功，则返回正常的回调应答，状态码为200。
- 如果重试后回调服务器仍无正常响应，则返回异常的回调应答，状态码为579。
自定义资源名说明
描述
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=
注：指令是可以组合的，多个指令用
;拼接起来即可。