JavaScript SDK for UCloud US3 (原名UFile 对象存储服务)
§ 说明
§ 安装
§ 示例
§ API列表
US3 JsSDK 主要用来从页面上传、下载、列表、删除文件。
SDK需要配合服务端 token_server.php 结合使用。先配置好环境,安装web服务器和解析php的服务。
部署SDK到服务器,配置好[安装](#install)中指定的4个参数,访问服务器地址,即可操作[示例](#examples)中的功能。
V2的示例支持SDK内部签名计算、服务端签名计算和上传回调。V1不再维护,以V2为准。
上传文件大致使用流程:
1、参考V2/demo
2、需要一个后端服务器,提供 token 生成的功能,类似 token_server.php; 在上传文件时,需要调用这个 php,实现 签名的生成;参考:https://github.com/ufilesdk-dev/ufile-sdk-auth-server
3、调用方法,具体参考 v2/demo 的代码。
4、具体流程:
a、js 初始化一个 UCloudUfile 对象,传入bucket 的参数,和 token server .php 的地址
b、token_server.php , 部署在用户自己的服务器上,主要是用来生成签名。
里面需要用户填入公私钥信息, 需要修改代码,按自己业务需求,对请求做自己业务的鉴权校验;
放在服务器的目的,主要是防止公私钥泄露,又能提供上传的签名服务。
c、js 调用 uploadFile 接口完成上传文件(uploadFile 里面,会去请求 token_server.php, 然后把数据传到 ucloud 的服务器)
注:在较高版本 chrome 中,chrome 会默认阻止非 https 内网请求,现象为请求发送不出去,控制台出现 `net::ERR_FAILED` 错误,这种情况下需要修改浏览器参数 block-insecure-private-network-requests 为 Disabled,允许浏览器发送非 https 内网请求。
SDK需要浏览器支持HTML5。
将src目录中的spark-md5-3.0.0.min.js和ufile.js引入到您的项目中,如下所示。
<script type="text/javascript" src="sdk/spark-md5-3.0.0.min.js"></script>
<script type="text/javascript" src="sdk/ufile.js"></script>
配置
bucketName
和bucketUrl
。
既可以在实例化时传参设置,也可以在src目录的ufile.js中全局设置。
配置
UCLOUD_PUBLIC_KEY
和UCLOUD_PRIVATE_KEY
。
在token_server.php中设置。
在UCloud控制台中可以查看您的API密钥的public_key
和private_key
。
如果浏览器控制台出现类似下面所示的错误提示:
XMLHttpRequest cannot load https://example-name.cn-bj.ufileos.com/?list&prefix=&marker=&limit=20.
Response to preflight request doesn't pass access control check:
The 'Access-Control-Allow-Origin' header contains the invalid value 'null'.
Origin 'http://localhost:8081' is therefore not allowed access.
则说明你的bucket地址(https://example-name.cn-bj.ufileos.com/)没有跨域设置,需要提交工单。
- 获取文件列表
- 查询文件信息
- 下载文件
- 删除文件
- 批量删除
- 普通上传
- 表单上传
- 分片上传
- 批量上传
参见SDK中examples目录中的示例。
目录中的jQuery和Bootstrap不是必须引入,只是为了方便演示。
获取Bucket的文件列表
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
名称 | 类型 | 说明 |
---|---|---|
BucketId | string | 对象存储空间ID |
BucketName | string | 对象存储空间名称 |
DataSet | array | 文件信息列表 |
NextMarker | string | 下一个标志字符串 |
名称 | 类型 | 说明 |
---|---|---|
BucketName | string | 对象存储空间名称 |
CreateTime | number | 文件创建时间 |
FileName | string | 文件名称 |
Hash | string | 文件ETag |
MimeType | string | 文件类型 |
ModifyTime | number | 文件修改时间 |
Size | number | 文件大小 |
ufile.getFileList(successCallBack, errorCallBack);
查询文件基本信息
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
fileName | true | string | 请求查询的文件名称 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
名称 | 类型 | 说明 |
---|---|---|
contentType | string | 文件类型 |
eTag | string | 文件eTag |
status | string | 返回的HTTP状态码。查询成功是200,失败是404 |
response | string | API返回的response |
ufile.getFileDetail(fileName, successCallBack, errorCallBack);
下载文件
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
fileName | true | string | 请求下载的文件名称 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
progress | false | function | 请求下载进度的回调函数 |
名称 | 类型 | 说明 |
---|---|---|
response | Blob。具体参见MDN | API返回的response |
名称 | 类型 | 说明 |
---|---|---|
size | number | 文件大小 |
type | string | 文件类型 |
名称 | 类型 | 说明 |
---|---|---|
response | number | 下载进度比例。已完成上传文件大小/总上传文件大小的值,位于0-1之间。 |
ufile.downloadFile(fileName, successCallBack, errorCallBack, progressCallBack);
删除文件
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
fileName | true | string | 请求删除的文件名称 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
ufile.deleteFile(fileName, successCallBack, errorCallBack);
批量删除
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
fileList | true | array | 请求删除的文件名称组成的数组 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
ufile.batchDelete(fileList, successCallBack, errorCallBack);
普通上传文件
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
data | true | object | 请求上传的参数 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
progress | false | function | 上传进度的回调函数 |
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
file | true | File。具体参见MDN | 请求上传的文件 |
fileRename | false | string | 文件的重新命名 |
名称 | 类型 | 说明 |
---|---|---|
response | number | 上传进度比例。已完成上传文件大小/总上传文件大小的值,位于0-1之间。 |
ufile.uploadFile(data, successCallBack, errorCallBack, progressCallBack);
说明:适合使用浏览器的场景并且上传文件内容可以在一次HTTP请求完成,并且所有PUT上传支持的参数都可以在表单上传中指定。
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
data | true | object | 请求上传的参数 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
file | true | File。具体参见MDN | 请求上传的文件 |
fileRename | false | string | 文件的重新命名 |
ufile.formUpload(data, successCallBack, errorCallBack);
说明:适合大文件上传
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
data | true | object | 请求上传的参数 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
progress | false | function | 上传进度的回调函数 |
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
file | true | File。具体参见MDN | 请求上传的文件 |
fileRename | false | string | 文件的重新命名 |
名称 | 类型 | 说明 |
---|---|---|
Bucket | string | 对象存储空间名称 |
Key | string | 文件名称 |
FileSize | string | 文件大小 |
名称 | 类型 | 说明 |
---|---|---|
status | string | 上传状态。init表示初始化分片;uploading表示分片上传中;uploaded表示完成分片。 |
value | number | 上传进度比例。已完成上传文件大小/总上传文件大小的值,位于0-1之间。 |
ufile.sliceUpload(data, successCallBack, errorCallBack, progressCallBack);
批量上传文件
名称 | 必选 | 类型 | 说明 |
---|---|---|---|
fileList | true | array | 批量上传的文件列表。File类型组成的数组列表 |
success | false | function | 请求成功的回调函数 |
error | false | function | 请求失败的回调函数 |
progress | false | function | 批量上传进度的回调函数 |
名称 | 类型 | 说明 |
---|---|---|
response | number | 上传进度比例。已完成上传文件大小/总上传文件大小的值,位于0-1之间。 |
ufile.batchUpload(fileList, successCallBack, errorCallBack, progressCallBack);