返回数据说明

更新时间:2020-10-09 13:48:59

场景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方便自定义返回给用户端的信息,当前可支持两种参数方式:自定义替换变量和特殊替换变量,两种方式可以随意组合使用。

注:

  1. 采用普通上传,returnBody内容默认返回文件hash值;采用分片上传,returnBody内容默认返回文件hash值及key。
  2. 设置了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)。 普通上传/分片上传
$(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) 访问该资源的实际路径。 普通上传/分片上传
$(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次,而后每隔1分钟重试一次(重试5次),共重试8次。

  1. 如果重试后回调成功,则返回正常的回调应答,状态码为200。
  2. 如果重试后回调服务器仍无正常响应,则返回异常的回调应答,状态码为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
$(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=

注:指令是可以组合的,多个指令用;拼接起来即可。

本篇文档内容对您是否有帮助?
有帮助
我要反馈
提交成功!非常感谢您的反馈,我们会继续努力做到更好!