BIMFACE服务器端API接口
源文件相关
在注册成为BIMFACE的应用开发者后,要能在浏览器里浏览你的模型或者获取你模型内的BIM数据, 首先需要把你的模型文件上传到BIMFACE。根据不同场景,BIMFACE提供了丰富的文件相关的接口。
文件相关所有接口都需要提供有效的Access Token。不支持View Token。 |
源文件上传
普通文件流上传
PUT https://file.bimface.com/upload
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Header |
Content-Type |
取值:application/octet-stream |
string |
Header |
Content-Length |
数据流文件长度 |
integer (int64) |
Query |
name |
文件的全名,使用URL编码(UTF-8),最多256个字符 |
string |
Query |
sourceId |
调用方的文件源ID,不能重复 |
string |
指定外部文件url方式上传
PUT https://file.bimface.com/upload
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Query |
etag |
文件etag |
string |
Query |
name |
文件的全名,使用URL编码(UTF-8),最多256个字符 |
string |
Query |
sourceId |
调用方的文件源ID,不能重复 |
string |
Query |
url |
文件所在url |
string |
文件直传
BIMFACE使用了分布式对象存储来存储用户上传的模型/图纸文件。如使用普通的文件上传接口, 文件流会通过BIMFACE的服务器,再流向最终的分布式存储系统,整个上传过程会受BIMFACE服务器的带宽限制,上传速度非最优。 如使用文件直传接口,开发者应用在申请到一个Policy凭证后,可以直接上传文件跟BIMFACE后台的分布式存储系统, 这样上传速度和稳定性都会有提升,是我们推荐的上传方式。
另外,很多BIMFACE应用都有自己的Web前端页面,这种情况我们也推荐使用文件直传接口。
获取文件直传的policy凭证
GET https://file.bimface.com/upload/policy
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Query |
name |
文件的全名,使用URL编码(UTF-8),最多256个字符 |
string |
Query |
sourceId |
调用方的文件源ID,不能重复 |
string |
HTTP响应示例
响应 200
{
"code" : "success",
"data" : {
"accessId" : "QLYNXu7B9OTjErYR",
"callbackBody" : "eyJjYWxsYmFja0JvZHlUeXBlIjoiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwiY2FsbGJhY2tIb3N0IjoiZmlsZS5iaW1mYWNlLmNvbSIsImNhbGxiYWNrVXJsIjoiaHR0cHM6Ly8xMTYuMjI4LjE5NS4xOC9vc3MvcmVjZWl2ZSIsImNhbGxiYWNrQm9keSI6Im9iamVjdD0ke29iamVjdH0mc2l6ZT0ke3NpemV9JmV0YWc9JHtldGFnfSZuYW1lPXRlc3QucGRmJmZpbGVJZD0xNDgzMDY1NTc0NzU0NTI4JmFwcGtleT1hRGxQZjEzVXRpR3M3eXVIQ2Q4ZUhTTEhiSEpUVThTZCZzb3VyY2VJZD0mZmlsZUJ1Y2tldD1iZi1kZXYtc3JjZmlsZSJ9",
"expire" : 1542792319,
"host" : "https://bf-dev-srcfile.oss-cn-shanghai.aliyuncs.com",
"objectKey" : "2f15df1c430b4ad3b0644029111b703a",
"policy" : "eyJleHBpcmF0aW9uIjoiMjAxOC0xMS0yMVQwOToyNToxOS45OTZaIiwiY29uZGl0aW9ucyI6W1siY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsNTM2ODcwOTEyMF0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCIiXV19",
"signature" : "q4NrZ1By/msuHOHlgpgX56mMUhY=",
"sourceId" : "a3da94969c054b3795cef542a6fb7bd6"
},
"message" : ""
}
根据policy凭证在web端上传文件
通过接口“https://file.bimface.com/upload/policy”获取文件直传的policy凭证后,可以直接在前端使用表单上传方式将文件上传到BIMFACE的对象存储上。
BIMFACE 控制台就是通过这种方式来实现文件上传的,可以F12→network查看请求详情。
以获取到的policy凭证为以下数据示例:
{ "code": "success", "message": null, "data": { "host": "https://bf-prod-srcfile.oss-cn-beijing.aliyuncs.com", "policy": "eyJleHBpcmF0aW9uIjoiMjAxOS0wOC0xNVQwNjowOTozMC41NTFaIiwiY29uZGl0aW9ucyI6W1siY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsMTA3Mzc0MTgyNF0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDAifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIiJdXX0=", "accessId": "5nGlEwOIzrwCVaDZ", "signature": "QGMtcEzm2KrVg7cr266CVMc9syM=", "expire": 1565849370, "callbackBody": "eyJjYWxsYmFja1VybCI6Imh0dHBzOi8vZmlsZS5iaW1mYWNlLmNvbS9vc3MvcmVjZWl2ZSIsImNhbGxiYWNrSG9zdCI6ImZpbGUuYmltZmFjZS5jb20iLCJjYWxsYmFja0JvZHkiOiJvYmplY3RcdTAwM2Qke29iamVjdH1cdTAwMjZzaXplXHUwMDNkJHtzaXplfVx1MDAyNmV0YWdcdTAwM2Qke2V0YWd9XHUwMDI2bmFtZVx1MDAzZHVwbG9hZFRlc3RfMjAxOTA1MTYucnZ0XHUwMDI2ZmlsZUlkXHUwMDNkMTY3MTk0ODkzMjkwODQ0OFx1MDAyNmFwcGtleVx1MDAzZHJPNzdrQXd1V3BXajZTMlRMVzdmSDJSS1NOWWNBcmxFXHUwMDI2c291cmNlSWRcdTAwM2RcdTAwMjZmaWxlQnVja2V0XHUwMDNkYmYtcHJvZC1zcmNmaWxlIiwiY2FsbGJhY2tCb2R5VHlwZSI6ImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9", "objectKey": "af20e3d3a0e44377b2260129a5e90402", "sourceId": null } }
通过表单方式上传时,请求的构造方式为:
名称 | 对应值 |
---|---|
请求url |
返回体中的host |
name |
请求体中的name |
key |
返回体中的objectKey |
policy |
返回体中的policy |
OSSAccessKeyId |
返回体中的accessId |
callback |
返回体中的callbackBody |
signature |
返回体中的signature |
success_action_status |
200 |
file |
需要上传文件的binary数据流 |
请求示例
POST / HTTP/1.1 Host: bf-prod-srcfile.oss-cn-beijing.aliyuncs.com User-Agent: PostmanRuntime/7.15.2 Accept: */* Postman-Token: 0c31cbde-ee57-4528-be60-7468bddf49b1,d7fb57d1-9df2-439a-bfe2-c6081365c21f Host: bf-prod-srcfile.oss-cn-beijing.aliyuncs.com Accept-Encoding: gzip, deflate Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Length: 5125934 Connection: keep-alive Content-Disposition: form-data; name="name" uploadTest_20190516.rvt ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="key" af20e3d3a0e44377b2260129a5e90402 ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="policy" eyJleHBpcmF0aW9uIjoiMjAxOS0wOC0xNVQwNjowOTozMC41NTFaIiwiY29uZGl0aW9ucyI6W1siY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsMTA3Mzc0MTgyNF0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDAifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIiJdXX0= ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="OSSAccessKeyId" 5nGlEwOIzrwCVaDZ ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="success_action_status" 200 ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="callback" eyJjYWxsYmFja1VybCI6Imh0dHBzOi8vZmlsZS5iaW1mYWNlLmNvbS9vc3MvcmVjZWl2ZSIsImNhbGxiYWNrSG9zdCI6ImZpbGUuYmltZmFjZS5jb20iLCJjYWxsYmFja0JvZHkiOiJvYmplY3RcdTAwM2Qke29iamVjdH1cdTAwMjZzaXplXHUwMDNkJHtzaXplfVx1MDAyNmV0YWdcdTAwM2Qke2V0YWd9XHUwMDI2bmFtZVx1MDAzZHVwbG9hZFRlc3RfMjAxOTA1MTYucnZ0XHUwMDI2ZmlsZUlkXHUwMDNkMTY3MTk0ODkzMjkwODQ0OFx1MDAyNmFwcGtleVx1MDAzZHJPNzdrQXd1V3BXajZTMlRMVzdmSDJSS1NOWWNBcmxFXHUwMDI2c291cmNlSWRcdTAwM2RcdTAwMjZmaWxlQnVja2V0XHUwMDNkYmYtcHJvZC1zcmNmaWxlIiwiY2FsbGJhY2tCb2R5VHlwZSI6ImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9 ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="signature" QGMtcEzm2KrVg7cr266CVMc9syM= ------WebKitFormBoundary7MA4YWxkTrZu0gW-- Content-Disposition: form-data; name="file"; filename="/C:/Users/jianqq/Downloads/b (1).rvt ------WebKitFormBoundary7MA4YWxkTrZu0gW--
断点续传
当文件比较大,或者所在网络网速较慢的情况下,单个文件上传的时间会比较长。如果中间有任何的网络错误, 本次上传就会被中断,那么文件就会需要重新上传,非常浪费时间。
为解决这个问题,BIMFACE提供了断点上传的接口,开发者可以利用这些接口对文件进行上传,即使上传过程种出现错误, 下一次也可以从上次错误的文件位置开始继续上传。
创建追加文件
POST https://file.bimface.com/appendFiles
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Query |
length |
上传文件长度 |
integer (int64) |
Query |
name |
文件的全名,使用URL编码(UTF-8),最多256个字符 |
string |
Query |
sourceId |
调用方的文件源ID,不能重复 |
string |
HTTP响应示例
响应 200
{
"code" : "success",
"data" : {
"appendFileId" : 1216113551663296,
"createTime" : "2017-11-09 13:25:03",
"file" : {
"createTime" : "2017-11-09 13:25:03",
"etag" : "19349858cjs98ericu989",
"fileId" : 1216113551663296,
"length" : 39044,
"name" : "-1F.rvt",
"status" : "success",
"suffix" : "rvt"
},
"length" : 39044,
"name" : "-1F.rvt",
"position" : 0,
"status" : "success"
},
"message" : ""
}
查询追加文件信息
GET https://file.bimface.com/appendFiles/{appendFileId}
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Path |
appendFileId |
追加文件id |
integer (int64) |
HTTP响应示例
响应 200
{
"code" : "success",
"data" : {
"appendFileId" : 1216113551663296,
"createTime" : "2017-11-09 13:25:03",
"file" : {
"createTime" : "2017-11-09 13:25:03",
"etag" : "19349858cjs98ericu989",
"fileId" : 1216113551663296,
"length" : 39044,
"name" : "-1F.rvt",
"status" : "success",
"suffix" : "rvt"
},
"length" : 39044,
"name" : "-1F.rvt",
"position" : 0,
"status" : "success"
},
"message" : ""
}
追加文件信息
POST https://file.bimface.com/appendFiles/{appendFileId}/data
参数
类型 | 名称 | 说明 | 类型 | 默认值 |
---|---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
|
Path |
appendFileId |
追加文件id |
integer (int64) |
|
Query |
position |
追加上传开始位置 |
integer (int64) |
|
HTTP响应示例
响应 200
{
"code" : "success",
"data" : {
"appendFileId" : 1216113551663296,
"createTime" : "2017-11-09 13:25:03",
"file" : {
"createTime" : "2017-11-09 13:25:03",
"etag" : "19349858cjs98ericu989",
"fileId" : 1216113551663296,
"length" : 39044,
"name" : "-1F.rvt",
"status" : "success",
"suffix" : "rvt"
},
"length" : 39044,
"name" : "-1F.rvt",
"position" : 0,
"status" : "success"
},
"message" : ""
}
源文件信息获取
获取文件信息
GET https://file.bimface.com/files/{fileId}
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Path |
fileId |
文件ID |
integer (int64) |
获取文件信息列表
GET https://file.bimface.com/files
参数
类型 | 名称 | 说明 | 类型 | 默认值 |
---|---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
|
Query |
endTime |
截止日期,格式为 yyyy-MM-dd |
string |
|
Query |
offset |
查询结果偏移,从查询结果的第offset条开始返回数据 |
integer (int64) |
|
Query |
rows |
查询结果数, 默认为100, 最大500 |
integer (int64) |
|
Query |
startTime |
起始日期,格式为 yyyy-MM-dd |
string |
|
Query |
status |
文件状态,uploading,success,failure |
string |
|
Query |
suffix |
文件后缀 |
string |
获取文件上传状态信息
GET https://file.bimface.com/files/{fileId}/uploadStatus
参数
类型 | 名称 | 说明 | 类型 |
---|---|---|---|
Header |
Authorization |
bearer {accessToken} |
string |
Path |
fileId |
文件ID |
integer (int64) |
源文件下载
源文件删除
数据实体类
AppendFileBean
名称 | 说明 | 类型 |
---|---|---|
appendFileId |
样例 : |
integer (int64) |
createTime |
样例 : |
string |
file |
样例 : FileBean |
|
length |
样例 : |
integer (int64) |
name |
样例 : |
string |
position |
样例 : |
integer (int64) |
status |
样例 : |
string |
FileBean
名称 | 说明 | 类型 |
---|---|---|
createTime |
样例 : |
string |
etag |
样例 : |
string |
fileId |
样例 : |
integer (int64) |
length |
样例 : |
integer (int64) |
name |
样例 : |
string |
status |
样例 : |
string |
suffix |
样例 : |
string |
FileUploadStatusBean
名称 | 说明 | 类型 |
---|---|---|
failedReason |
样例 : |
string |
fileId |
样例 : |
integer (int64) |
name |
样例 : |
string |
status |
样例 : |
string |
GeneralResponse
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : |
object |
message |
样例 : |
string |
GeneralResponse«AppendFileBean»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : AppendFileBean |
|
message |
样例 : |
string |
GeneralResponse«FileBean»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : FileBean |
|
message |
样例 : |
string |
GeneralResponse«FileUploadStatusBean»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : FileUploadStatusBean |
|
message |
样例 : |
string |
GeneralResponse«List«FileBean»»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : |
< FileBean > array |
message |
样例 : |
string |
GeneralResponse«SupportFileBean»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : SupportFileBean |
|
message |
样例 : |
string |
GeneralResponse«UploadPolicyBean»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : UploadPolicyBean |
|
message |
样例 : |
string |
GeneralResponse«string»
名称 | 说明 | 类型 |
---|---|---|
code |
样例 : |
string |
data |
样例 : |
string |
message |
样例 : |
string |
SupportFileBean
名称 | 说明 | 类型 |
---|---|---|
length |
样例 : |
integer (int64) |
types |
样例 : |
< object > array |
UploadPolicyBean
名称 | 说明 | 类型 |
---|---|---|
accessId |
样例 : |
string |
callbackBody |
样例 : |
string |
expire |
样例 : |
integer (int64) |
host |
样例 : |
string |
objectKey |
样例 : |
string |
policy |
样例 : |
string |
signature |
样例 : |
string |
sourceId |
样例 : |
string |