Storage - 云平台二次开发文档

Storage服务

1.服务功能

云平台提供了Storage服务，主要提供文件存储，大型文件的分片存储，文件分享，上传，下载等；
文件主要存储在阿里云等云端服务器，保障了您文件的安全存储，通过网页让您可以在线浏览建筑资料图片；
云平台针对数据安全要求较高的用户，还提供了私有化部署的方式，分布式存储等方式；

2.使用场景

目前建筑行业发展越来越迅速，云存储越来越适合时代发展的潮流；
云平台文件存储适合多种格式，大型文件的存储，高速下载，高速上传，文件资料的安全性，隐私性存储和下载；
目前云平台提供免费试用版，用户可以先进行体验，后期再注册商业版模式，以提供更大的存储空间和更多的文件存储权限；

Bucket存储服务

1.创建一个新的Bucket

POST https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets

注：Bucket是存储文件的存储容器，为保障文件资源存储信息安全，我们将不提供删除和重名命Bucket接口。请谨慎命名，合理使用本接口！

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucket_key	String	是	Bucketkey是bucket中的唯一标识
grant_type	String	否	private(私有), public-read(公共读), public-read-write(公共读写), 缺省值是private(私有)

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
id	String	Bucket的Id
client_id	String	服务的 Client Id
bucket_key	String	Bucketkey是bucket中的唯一标识
owner	String	资源拥有者的clientId
grant_type	String	private(私有), public-read(公共读), public-read-write(公共读写), 缺省值是private(私有)
create_at	Timestamp	Bucket 创建时间的时间戳

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

    https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets

选择文件接口类型

2.获取所有Bucket

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
count	Integer	Bucket 对象模型的数量
id	String	Bucket id
client_id	String	Bucket 所属的 ClientId
bucket_key	String	Bucket 的唯一 key
owner	String	资源拥有者的clientId
grant_type	String	private(私有), public-read(公共读), public-read-write(公共读写), 缺省值是private(私有)
create_at	Timestamp	Bucket 创建时间的时间戳
update_at	Timestamp	Bucket 修改时间的时间戳

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

    https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets

选择文件接口类型

3.获取Bucket的对象模型信息

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
count	Integer	Bucket 对象模型的数量
id	String	Bucket id
client_id	String	Bucket 所属的 Client id
bucket_key	String	Bucket 的唯一 key
owner	String	资源拥有者的clientId
grant_type	String	类型
create_at	Timestamp	Bucket 创建时间的时间戳
update_at	Timestamp	Bucket 修改时间的时间戳

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

    https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/string

选择文件接口类型

4.在指定的 Bucket 中新建一个文件 Object

PUT https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求头（HEARDER）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
Content-Type	String	是	application/octet-stream

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	bucket 的key值
objectKey	String	是	object 的key值
objectKeyEncoding	String	否	根据objectkey决定是否添加此参数
md5	String	否	md5不填就要上传文件，md5传了就不需要上传文件了, 使用md5秒传的前提是文件上传过

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
binary	String		上传文件

注释：在指定的 Bucket 中新建一个文件 Object , 如果objectKey 参数为空, 文件 Object Key 为 body 中的 file 参数的文件名称。Body 中的文件 Object 内容格式为 multipart/form-data 注释：域名后边直接加上传url也可以实现上传功能路径的差别就在/zuul

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
id	String	Bucket id
client_id	String	Bucket 所属的 Client id
object_key	String	Object 的唯一 key
owner	String	资源拥有者的clientId
size	String	Object 数据内容的大小 (Byte)
create_at	Timestamp	Bucket 创建时间的时间戳
md5	String	文件指纹md5值

注释：objectKeyEncoding此属性是非必填项， https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/4qpLJvKnSSD_bucket/objects/5Yqe5YWs5qW8IC5wbW9kZWw=?objectKeyEncoding=base64 其中objectKeyEncoding的存在是为了解决objectkey使用过程中出现名称中含有空格、非法字符等问题，objectKeyEncoding=base64这样使用时objectkey 的值需要进行base64进行加密，这样可以解决上传文件名称和下载文件时候的名称不符的问题（例后缀名称丢失），下载时的名称是objectkey的名称，而不是上传文件的文件名称，如果想解决名称统一的问题，需要把objectkey的名称改成和文件名称一致。

选择文件接口类型

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

 https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/key/objects/key

选择文件接口类型

5.在指定的 Bucket 中新建一个文件 Object(通过签名)

POST https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	bucket 的key值
objectKey	String	是	object 的key值
md5	String	否	文件指纹md5值

请求头（HEARDER）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
Content-Type	String	是	application/octet-stream
x-bimserver-upload-url	String	是	签证的值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
binary	String		上传文件

注释：在指定的 Bucket 中新建一个文件 Object , 如果objectKey 参数为空, 文件 Object Key 为 body 中的 file 参数的文件名称。Body 中的文件 Object 内容格式为 multipart/form-data

调用过程:

选择文件接口类型

注释：首先通过此接口获得signature和uploadUrl

选择文件接口类型

注释：其次将uploadUrl放入路径中

选择文件接口类型

注释：通过此种方式也可以完成上传

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
id	String	Bucket id
client_id	String	Bucket 所属的 Client id
object_key	String	Object 的唯一 key
owner	String	资源拥有者的clientId
size	String	Object 数据内容的大小 (Byte)
create_at	Timestamp	Bucket 创建时间的时间戳
md5	String	文件指纹md5值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

注：如果需要输入签名，则不需要进行Authorization认证

请求示例演示:

请求路径：

 https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/key/objects/key

选择文件接口类型

6.获取指定的Bucket中所有文件的Object的对象的模型数据

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
count	Integer	Bucket 对象模型的数量
objects	String	Object 对象模型的集合
id	String	Object ID
client_id	String	Object 所属的 Client ID
owner	String	资源拥有者的clientId
size	Long	Object 数据内容的大小 (Byte)
create_at	Timestamp	Object 创建时间的时间戳

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

    https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/string/objects

选择文件接口类型

7.删除指定的Bucket中某个的文件Object模型数据

DELETE https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Path）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key
objectKey	String	是	Object 的唯一 key
objectKeyEncoding	String	否	根据objectkey决定是否添加此参数

使用objectKeyEncoding参数时，请求的url为：

https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}?objectKeyEncoding=base64

objectKeyEncoding的存在是为了解决objectkey使用过程中出现名称中含有空格、非法字符等问题， objectKeyEncoding=base64这样使用时objectkey的值需要进行base64进行加密。

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/ey/objects/key

选择文件接口类型

8.修改指定的Bucket中一个文件Object的对象模型

PUT https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}/info?objectKeyEncoding=base64

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Path）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key
objectKey	String	是	Object 的唯一 key

请求参数（Query）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
objectKeyEncoding	String	否	如果objectkey用base64加密，则添加这个参数值为base64；反之，如果填写了这个参数，objectkey需要用base64加密

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
client_id	String	否	Object 所属的 Client ID
create_at	Timestamp	否	Object 创建时间的时间戳
ext_attr	Object	是	自定义扩展属性值。 'filename'修改模型树根节点文件名
id	String	否	Object ID
md5	String	否	md5值
object_key	String	否	Object 键值
owner	String	否	Object 所属的 Owner
size	Integer	否	Object 数据内容的大小 (Byte)

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
object_key	String	Object 的唯一 key
md5	String	md5值
id	String	Object ID
client_id	String	Object 所属的 Client ID
owner	String	Object 所属的 Owner
size	Integer	Object 数据内容的大小 (Byte)
ext_attr	Object	自定义扩展属性值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

 https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/rvt_bucket/objects/Mi0zX3J2dA/info?objectKeyEncoding=base64

选择文件接口类型

9.获取指定的Bucket中一个文件Object的对象模型

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}/info

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Path）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key
objectKey	String	是	Object 的唯一 key

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
id	String	Bucket id
client_id	String	Bucket 所属的 Client id
object_key	String	Object 的唯一 key
owner	String	资源拥有者的clientId
size	String	Object 数据内容的大小 (Byte)
create_at	Timestamp	Bucket 创建时间的时间戳
md5	String	文件指纹md5值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

 https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/key/objects/key

选择文件接口类型

10.获取指定的Bucket中一个文件的object的底层预签名Url。客户端可以通过这个url直接用GET方法下载object

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}/directpresignedurl?expiration=xxx

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Params）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
expiration	Integer	否	设置的过期时间
objectKeyEncoding	String	否	如果用objectkey用base64加密, 则添加这个参数值为base64

请求参数（Path）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key
objectKey	String	是	Object 的唯一 key

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
url	String	下载的url

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

  https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/bucketkey/objects/objectkey/directpresignedurl?expiration=300

选择文件接口类型

11.获取指定的 Bucket 中一个文件 Object 的数据内容。对象Key为指定Key

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/{bucketKey}/objects/{objectKey}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	bucket 的key值
objectKey	String	是	object 的key值
objectKeyEncoding	String	否	如果使用objectKeyEncoding=base64 则objectkey需要进行base64加密
clientId	String	否	文件展示权限如果设置永久时效需要加上clientId的值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
文件内容

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

 https://api.cloud.pkpm.cn/bimserver/storage/v3/buckets/key/objects/key

选择文件接口类型

Object相关服务

12.根据 Object ID 获取文件 Object 的数据内容

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/objects/{objectId}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
objectId	String	是	object中返回的id值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
文件内容

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/objects/xxxxx

选择文件接口类型

13.根据 Object ID 获取对应的文件 Object 的对象模型

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/objects/{objectId}/info

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
objectId	String	是	object中返回的Id值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
id	String	Bucket id
client_id	String	Bucket 所属的 Client id
object_key	String	Object 的唯一 key
owner	String	资源拥有者的clientId
size	String	上传文件大小
create_at	Timestamp	Bucket 创建时间的时间戳
md5	String	文件指纹md5值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/objects/Rxxxxx/info

选择文件接口类型

14.批量获取访问文件 ObjectKey的签名

POST https://api.cloud.pkpm.cn/bimserver/storage/v3/signedObjects

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
clientId	String	否	Client Id
expire	Long	否	过期时间，单位为秒
urns	List<String>	否	Storage Urn 集合

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
urn	Map< String,String >

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/signedObjects

选择文件接口类型

15.通过签名认证的方式来获得一个Object的数据内容

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/signedObjects/buckets/bucketkey/objects/objectkey?signature=xxx

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Params）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
signature	String	是	签证

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
文件内容

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/signedObjects=asasa

选择文件接口类型

16.根据type获取文件上传需要的url

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/uploadUrl?bucketKey=xxx&expire=xxx&objectKey=xxx&type=xxx

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Params）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	Bucket 的唯一 key
expire	Integer	否	超时时间
objectKey	String	根据type传入的值来判断	object 的唯一key
type	String	是	7：以form-data的方式上传object，此接口必须指定objectKey 8：以二进制流的方式上传object，此接口必须指定objectKey 9：以form-data的方式上传object，可以不指定objectKey，系统默认会取文件的名称作为objectKey

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
type	Integer	需要获取的url的类型
expire	Integer	超时时间
uploadUrl	String	上传路径
callbackUrl	String	回调路径
signature	String	签证
description	String	描述

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

   https://api.cloud.pkpm.cn/bimserver/storage/v3/uploadUrl?bucketKey=bucketkey&expire=60000&objectKey=objectkey&type=8

选择文件接口类型

秒传

发起秒传的流程：（走秒传流程的关键是要确定文件已经存在于服务器）
1.计算文件的MD5值；
2.探查文件是否存在于服务器；
探查文件是否存在与服务器有两种方式（实际操作中二选一即可）
方式一：请参考以下步骤17 https://cloud.pkpm.cn/devcenter/help/server-api/docs/Storage/#_17
方式二：请参考以下步骤18https://cloud.pkpm.cn/devcenter/help/server-api/docs/Storage/#18-md5

17. 计算文件的 MD5 值

请参考 https://cloud.pkpm.cn/devcenter/help/server-api/docs/Storage/#_27 完整示例中 getFileMd5 方法详细说明

18. 探查文件是否存在于服务器

POST https://api.cloud.pkpm.cn//bimserver/storage/v3/file/detectFileExists

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
md5	String		文件md5值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
status	Integer	状态

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn//bimserver/storage/v3/file/detectFileExists

选择文件接口类型

19. 通过md5判断文件是否存在

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/unique/md5/{md5}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
md5	String	否	文件的md5值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/unique/md5/1

选择文件接口类型

注：所有路径中{objectKey}均可以进行base64进行编码，然后路径中加入objectKeyEncoding参数用query形式拼接，如objectKeyEncoding=base64；这种形式是比较推荐的。

注：md5不填就要上传文件，md5传了就不需要上传文件了,使用md5秒传的前提是文件上传过。文件元数据不需要传到服务器，只需要把 MD5 值和 bucketKey 和 objectKey 传到服务器即可

分片上传服务

发起分片上传服务的流程：
分片上传服务完整示例：https://cloud.pkpm.cn/devcenter/help/server-api/docs/Storage/#_28
1.探查文件是否存在于服务器;
2.初始化分片上传;
3.列出分片数据；
4.逐个上传分片文件；
5.完成分片上传；
6.定位文件到objectKey；

20.探查文件是否存在于服务器

POST https://api.cloud.pkpm.cn//bimserver/storage/v3/file/detectFileExists

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
md5	String		文件md5值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
status	Integer	状态

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn//bimserver/storage/v3/file/detectFileExists

选择文件接口类型

21.通过md5判断文件是否存在

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/unique/md5/{md5}

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
md5	String	否	文件的md5值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/unique/md5/1

选择文件接口类型

注：所有路径中{objectKey}均可以进行base64进行编码，然后路径中加入objectKeyEncoding参数用query形式拼接，如objectKeyEncoding=base64；这种形式是比较推荐的。

注：md5不填就要上传文件，md5传了就不需要上传文件了,使用md5秒传的前提是文件上传过。

22.初始化分片上传（1）

POST https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/init

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
uploadId	String	上传id

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/init

选择文件接口类型

23.列出分片数据

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/parts?uploadId=xxx

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Params）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
uploadId	String	是	上传id

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
uploadId	String	分片上传Id
parts	String	数据

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/parts?uploadId=6214B953C2CCB4

选择文件接口类型

24.逐个上传分片文件（2）

POST https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/upload?uploadId=xxx&partNumber=xxx

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（Params）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
uploadId	String	是	分片上传Id
partNumber	Integer	是	分片号,取值[1-1000]

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
binary	String		上传文件

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
partNumber	Integer	分片上传Id
partSize	Integer	分片文件大小
partETag	String	分片文件的摘要值
createAt	Timestamp	创建时间

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/upload?uploadId=66E18CA214B953C2CCB4&partNumber=50

选择文件接口类型

25.完成分片上传（3）

POST https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/complete

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
md5	String	必填	文件md5值
partETag	String	必填	分片上传的分片实体标识,用于完成分片上传的数据检测
partNumber	Integer	必填	分片号（1.2.3...）

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
clientId	String	Client ID
createBy	String	创建者
md5	String	文件md5值
size	Long	文件大小

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因

请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/object/multipart/complete

选择文件接口类型

26.获取上传的URL

GET https://api.cloud.pkpm.cn/bimserver/storage/v3/uploadUrl?type=7&expire=60000&bucketKey=first_bucket&objectKey=first-model

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
type	Integer	必填	二次开发用户对应的 type 为 7
type	expire	必填	expire 为过期时间，单位为秒，开发者需要合理设置这个时间
bucketKey	String	必填	创建的容器
objectKey	String	必填	创建的容器中文件对象的 key

响应体（BODY）:

名称（Name）	类型（Type）	描述（Description）
uploadurl	String	上传文件的url
signature	String	自定义的数据类型,进行上传文件时传入x-bimserver-upload-url 的值

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因
##### 请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/uploadUrl?type=7&expire=60000&bucketKey=first_bucket&objectKey=first-model

选择文件接口类型

27.上传文件（基于上一步）

POST https://api.cloud.pkpm.cn/zuul/bimserver/storage/v3/buckets/first_bucket/object/first-model

授权（Authorization）:

名称（Name）	值(Value)	描述（Description）
Type	Bearer Token	Token拼装形式
Token	token值

请求参数（PATH）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
md5	String	否	文件的md5值，分片上传时为必填值

请求体（BODY）:

名称（Name）	类型（Type）	必填（Required）	描述（Description）
bucketKey	String	是	创建的容器
objectKey	String	是	创建的容器中文件对象的 key
Content-Type	String	是	application/octet-stream，分片上传时固定为"false"
x-bimserver-upload-url	String	是	步骤26中返回结果的 signature值
`分片上传时，Content-Type为"false"，不需要再上传文件数据，请求参数中拼接文件md5`

响应消息（MESSAGES）:

HTTP状态码	原因
401	未授权，请检查Authorization的Header的Access Token是否设置正确
403	无权访问请求的资源
404	Not Found
409	将要创建的资源已经存在，拒绝重复创建
500	服务内部错误，请查看详细的错误原因
##### 请求示例演示:

请求路径：

https://api.cloud.pkpm.cn/bimserver/storage/v3/uploadUrl?type=7&expire=60000&bucketKey=first_bucket&objectKey=first-model

分片上传服务完整示例

发起分片上传服务的流程：
1.计算文件的MD5值；详情请參考分片上传完整示例中 getFileMd5 方法详细说明
2.初始化分片上传:告诉服务器，开始分片上传；详情请參考分片上传完整示例中 SliceUpload.initSlice 方法
3.列出分片数据，用来处理分片上传的每一个数据；详情请參考分片上传完整示例中 SliceUpload.sliceFile 方法
4.逐个上传分片文件：将一个切片上传到服务器，然后循环‘列出分片数据’、‘逐个上传分片文件’步骤，直到所有的分片文件上传完成；详情请参考分片上传完整示例中SliceUpload.uploadSlice 方法
5.完成分片上传：告诉服务器，分片上传已经完成；详情请參考分片上传完整示例中 SliceUpload.completeSlice 方法
6.定位文件到objectKey：将分步上传的文件，通过 md5，指定给 bucketKey 下的 objectKey；详情请参考分片上传完整示例中 SliceUpload.uploadFile 方法

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>分片上传</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.12.1/jquery.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/spark-md5/3.0.0/spark-md5.js"></script>
  </head>
  <body>
    <input type="file" id="file" />
    <button onclick="getAccessToken()">获取Token</button>

    <button onclick="uploadFile()">分片上传</button>
    <script>
      /**
       * ENV.host 是要访问的后台服务地址
       * client_id 和 client_secret 是开发账号和密码
       * bucketKey 是已经创建好的 不然会报错
       * objectKey 是要上传文件的key
       */

      const ENV = {
        host: "api.cloud.pkpm.cn",
      };
      // 请不要在实际项目使用这种方式 获取token
      const authentication = {
        client_id: "", // 填写自己的 client_id
        client_secret: "", // 填写自己的 client_secret
        grant_type: "client_credentials",
        baseUrl: "https://" + ENV.host,
      };

      const bucketKey = "viewing_bucket";
      const objectKey = "viewing_object_test";

      let token;

      /**
       * 分片上传的入口函数
       * @return {Promise<void>}
       */
      async function uploadFile() {
        const file = document.getElementById("file").files[0];
        const md5 = await getFileMd5(file);
        const option = {
          file,
          md5,
        };
        new SliceUpload().sliceFile(option);
      }

      function getAccessToken() {
        // 组装完整的 API 路径
        const url = authentication.baseUrl + "/bimserver/auth/oauth/token";
        // 创建 form data
        const params =
          "client_id=" +
          authentication.client_id +
          "&client_secret=" +
          authentication.client_secret +
          "&grant_type=" +
          authentication.grant_type;
        $.ajax({
          type: "post",
          url: url,
          data: params,
          headers: { "Content-type": "application/x-www-form-urlencoded" },
          success: function (res) {
            token = res.access_token;
          },
          error: function (err) {
            console.log(err);
          },
        });
      }

      /**
       * 步骤1 计算文件的MD5值
       * 获取文件的md5值，在后续的操作会用到，这个方法依赖一个库 spark-md5 用来计算MD5值
       * 可以通过链接的方式加载 https://cdnjs.cloudflare.com/ajax/libs/spark-md5/3.0.0/spark-md5.js
       * 还可以通过包管理器 npm 加载 npm install --save spark-md5
       * github https://github.com/satazor/js-spark-md5
       * @param file 要获取md5值的文件
       * @return {Promise<string>}
       */
      function getFileMd5(file) {
        return new Promise((resolve, reject) => {
          const blobSlice =
              File.prototype.slice ||
              File.prototype.mozSlice ||
              File.prototype.webkitSlice,
            chunkSize = 2097152, // Read in chunks of 2MB
            chunks = Math.ceil(file.size / chunkSize),
            spark = new SparkMD5.ArrayBuffer(),
            fileReader = new FileReader();
          let currentChunk = 0;

          fileReader.onload = (e) => {
            console.log("read chunk nr", currentChunk + 1, "of", chunks);
            // @ts-ignore
            spark.append(e.target.result); // Append array buffer
            currentChunk++;

            if (currentChunk < chunks) {
              loadNext();
            } else {
              const md5 = spark.end();
              resolve(md5);
              console.log("finished loading");
              console.info("computed hash", md5); // Compute hash
            }
          };

          fileReader.onerror = (ev) => {
            reject(ev);
            console.warn("oops, something went wrong.");
          };

          const loadNext = () => {
            const start = currentChunk * chunkSize;
            const end =
              start + chunkSize >= file.size ? file.size : start + chunkSize;

            fileReader.readAsArrayBuffer(blobSlice.call(file, start, end));
          };

          loadNext();
        });
      }

      /**
       * 这个类是用来处理分片上传的每一个切片
       */
      class SliceUpload {
        // 每个文件切片大小定为10M
        BYTES_PER_SLICE = 10485760;
        // 当前分片上传的Id
        uploadId = "";
        // 每一个切片上传的记录，所有的切片上传完成后，会传给后台
        partETags = [];
        // 已发送切片的数量
        currentChunk = 0;
        // 总切片的数量
        chunks = 0;
        // 用来处理和后台发送请求的类
        uploadService = new UploadService(authentication.baseUrl);

        /**
         * 主要是来处理分片上传的逻辑
         * @param options
         * @return {Promise<*>}
         */
        async sliceFile(options) {
          try {
            // 初始化 分片上传
            this.uploadId = await this.initSlice();
            const file = options.file;
            // 每片 的 大小
            const chunkSize = this.BYTES_PER_SLICE;
            // 总片
            this.chunks = Math.ceil(file.size / chunkSize);

            // 如果下一片 小于总的片数
            while (this.currentChunk < this.chunks) {
              // 每片的开始
              const start = this.currentChunk * chunkSize;
              // 每片的结束
              const end =
                start + chunkSize >= file.size ? file.size : start + chunkSize;
              // 当前的要上传的切片
              const slice = file.slice(start, end);
              await this.uploadSlice(slice);
              // 下一片
              ++this.currentChunk;
            }
            // 所有的切片上传完了，并将md5值传给后台
            await this.completeSlice(options.md5);
            // 将刚刚上传的文件，通过md5， 指定给 bucketKey下的 objectKey，
            return this.uploadFile(options.md5);
          } catch (e) {
            console.error(e);
          }
        }

        /**
         * 上传一个切片
         * @param slice
         * @return {Promise<void>}
         */
        async uploadSlice(slice) {
          // 上传
          const formData = new FormData();
          formData.append("partFile", slice);
          const { partETag, partNumber } = await this.uploadService.uploadSlice(
            {
              uploadId: this.uploadId,
              partNumber: 1 + this.currentChunk,
              data: formData,
            }
          );

          this.partETags.push({ partETag, partNumber });
        }

        /**
         * 所有的切片上传好了，调用此方法
         * @param md5
         * @return {*|Promise<any>}
         */
        completeSlice(md5) {
          const data = {
            md5: md5,
            partETags: this.partETags,
            uploadId: this.uploadId,
          };
          return this.uploadService.completeSlice(data);
        }

        /**
         * 步骤2 初始化分片上传
         * @return {Promise<*>}
         */
        async initSlice() {
          const { uploadId } = await this.uploadService.initSlice();
          return uploadId;
        }

        /**
         * 将刚刚上传的文件，通过md5， 指定给 bucketKey下的 objectKey，
         * @param md5
         * @return {Promise<*>}
         */
        uploadFile(md5) {
          // bucketKey 已经创建好了
          const data = {
            bucketKey,
            objectKey,
            md5: md5,
          };
          return this.uploadService.getUrlUploadFile(data);
        }
      }

      /**
       * 用来处理和后台发送请求的类
       */
      class UploadService {
        constructor(baseUrl) {
          this.baseUrl = baseUrl;
        }

        /**
         * 初始化分片上传
         * @return {Promise<*>}
         */
        initSlice() {
          return new Promise((resolve, reject) => {
            $.ajax({
              type: "POST",
              url: this.baseUrl + "/bimserver/storage/v3/object/multipart/init",
              beforeSend(request) {
                request.setRequestHeader("Authorization", "Bearer " + token);
                request.setRequestHeader("Content-Type", "application/json");
              },
              success(res) {
                resolve(res.data);
              },
              error(err) {
                reject(err);
              },
            });
          });
        }

        /**
         * 步骤3 列出已经上传的切片
         * @return {Promise<*>}
         */
        partsSlice(uploadId) {
          return new Promise((resolve, reject) => {
            $.ajax({
              type: "GET",
              url:
                this.baseUrl +
                `/bimserver/storage/v3/object/multipart/parts?uploadId=${uploadId}`,
              beforeSend(request) {
                request.setRequestHeader("Authorization", "Bearer " + token);
              },
              success(res) {
                resolve(res.data);
              },
              error(err) {
                reject(err);
              },
            });
          });
        }

        /**
         * 步骤4 逐个上传分片文件
         * 上传一个切片
         * @return {Promise<*>}
         */
        uploadSlice({ uploadId, partNumber, data }) {
          return new Promise((resolve, reject) => {
            $.ajax({
              type: "POST",
              data,
              url:
                this.baseUrl +
                `/zuul/bimserver/storage/v3/object/multipart/upload?uploadId=${uploadId}&partNumber=${partNumber}`,
              beforeSend(request) {
                request.setRequestHeader("Authorization", "Bearer " + token);
              },
              contentType: false,
              processData: false,
              cache: false,
              dataType: "json",
              success(res) {
                resolve(res.data);
              },
              error(err) {
                reject(err);
              },
            });
          });
        }

        /**
         * 步骤5 完成分片上传
         * 告诉后台服务 所有的切片上传完成了
         */
        completeSlice(data) {
          return new Promise((resolve, reject) => {
            $.ajax({
              type: "POST",
              data: JSON.stringify(data),
              url:
                this.baseUrl +
                "/bimserver/storage/v3/object/multipart/complete",
              beforeSend(request) {
                request.setRequestHeader("Authorization", "Bearer " + token);
                request.setRequestHeader("Content-Type", "application/json");
              },
              dataType: "json",
              success(res) {
                resolve(res.data);
              },
              error(err) {
                reject(err);
              },
            });
          });
        }

        /**
         * 将获取上传的url和上传文件 封装成一个方法
         */
        async getUrlUploadFile({ bucketKey, objectKey, md5 }) {
          const uploadUrlData = await this.getUploadUrl({
            bucketKey,
            objectKey,
          });
          return this.uploadFile({ uploadUrlData, md5 });
        }

        /**
         * 获取上传的url
         * @param bucketKey
         * @param objectKey
         * @return {Promise<any>}
         */
        getUploadUrl({ bucketKey, objectKey }) {
          return new Promise((resolve, reject) => {
            $.ajax({
              type: "GET",
              url:
                this.baseUrl +
                `/bimserver/storage/v3/uploadUrl?type=7&expire=600000&bucketKey=${bucketKey}&objectKey=${objectKey}`,
              beforeSend(request) {
                request.setRequestHeader("Authorization", "Bearer " + token);
              },
              success(res) {
                resolve(res.data);
              },
              error(err) {
                reject(err);
              },
            });
          });
        }

        /**
         * 步骤6 定位文件到objectKey：将分步上传的文件，通过 md5，指定给 bucketKey 下的 objectKey
         * 上传文件
         * @param uploadUrlData
         * @param md5
         * @return {Promise<any>}
         */
        uploadFile({ uploadUrlData, md5 }) {
          return new Promise((resolve, reject) => {
            const url = this.baseUrl + uploadUrlData.uploadUrl + `&md5=${md5}`;
            $.ajax({
              type: "POST",
              url,
              beforeSend(request) {
                request.setRequestHeader("Authorization", "Bearer " + token);
                request.setRequestHeader(
                  "x-bimserver-upload-url",
                  uploadUrlData.signature
                );
              },
              contentType: false,
              processData: false,
              cache: false,
              dataType: "json",
              success(res) {
                alert("上传成功");
                resolve(res.data);
              },
              error(err) {
                reject(err);
              },
            });
          });
        }
      }
    </script>
  </body>
</html>