创建文件项

要使用文件管理服务丰富的API，第一步需要在存储中心中创建文件项。本节将介绍如何在项目创建文件项。

• 准备阶段

在创建文件项前，您需要获取有效的Access Token，有关Access Token 的详细说明和具体操作，请参见 Access Token (opens new window)。

文件上传前，请确认文件名称不包含特殊字符，/ \n  * \ <> | " : ?，否则无法上传成功。

1. 查找Hub空间

文件管理服务提供获取Hub列表 (opens new window) 接口，帮助您查询您的账号已注册哪些存储中心（Hub），您可以将文件上传到已注册的存储空间中。

HTTP请求示例

请求 path

GET https://api.bimface.com/bdfs/domain/v1/hubs

请求 header

"Authorization: Bearer cn-e9725999-0b36-4c0e-bdca-38ea88888888"

HTTP响应示例

响应 200

{
  "code" : "success",
  "data" : [ {
    "appKey" : "odatvZYUSAWMbdUjTU8HoZXB9tFt6123",
    "createTime" : "2022-02-02 02:02:02",
    "id" : "10000000000060002",
    "info" : "BIMFACE的hub",
    "name" : "BIMFACE",
    "tenantCode" : "BIMFACE",
    "updateTime" : "2022-02-02 02:02:02"
  } ],
  "message" : "success"
}

2. 查找到文件所属的Project

上一步您查找到了您账户注册的存储中心（Hub），假设您已经注册了"BIMFACE"的存储中心，请记住上一节响应正文中的id字段，它代表了HubId（10000000000060002）。

您需要在接口获取项目列表 (opens new window)中使用HubId，来获取可使用的项目列表（Project），正如基本概念里所说，创建项目（Project）的同时会自动创建对应的根文件夹，所有的文件会存放于项目的根文件夹下。

HTTP请求示例

请求 path

GET https://api.bimface.com/bdfs/domain/v1/hubs/10000000000060002/projects

请求 header

"Authorization: Bearer cn-e9725999-0b36-4c0e-bdca-38ea88888888"

HTTP响应示例

响应 200

{
  "code" : "success",
  "data" : [ {
    "appKey" : "odatvZYUSAWMbdUjTU8HoZXB9tFt6123",
    "createTime" : "2022-02-02 02:02:02",
    "hubId" : "10000000000060002",
    "id" : "10000000006016",
    "info" : "图纸对比的项目中心",
    "name" : "图纸对比",
    "tenantCode" : "BIMFACE",
    "thumbnail" : "https://static.bimface.com/bdfs/project/thumbnail/8e21fc91481e42ce805f0db938e04958_200X150.png",
    "type" : "NORMAL",
    "updateTime" : "2022-02-02 02:02:02"
  } ],
  "message" : "success"
}

3. 查询项目的根文件夹信息

在上一步中，您查找到了文件存放的项目信息，假设您将在项目“图纸对比”中上传文件，请记住该项目的id字段(10000000006016)，您需要在获取项目根文件夹信息 (opens new window)和创建文件项相关的接口中使用projectId。

这一步将介绍根文件夹的概念，每个项目都有唯一且对应的根文件夹，根文件夹会跟随项目自动创建，所有存放于该项目的文件都位于根文件夹下。

您可在这一步查询根文件夹的信息。根文件夹的信息（例如id和path）可用于查询项目下文件列表 (opens new window)和普通文件流上传 (opens new window)；由于在BIMFACE中，项目ID和根文件夹ID相同，若您想直接在项目根目录下上传文件、创建文件夹，也可将项目ID作为parentId填入参数，这样您可直接跳过这一步。

HTTP请求示例

请求 path

https://api.bimface.com/bdfs/v1/domain/hubs/10000000000060002/projects/10000000006016/root-folder

请求 header

"Authorization: Bearer cn-e9725999-0b36-4c0e-bdca-38ea88888888"

HTTP响应示例

响应 200

{
  "code" : "bimfaceservice-0000",
  "data" : {
    "appKey" : "odatvZYUSAWMbdUjTU8HoZXB9tFt6123",
    "createTime" : "2022-02-02 02:02:02",
    "id" : "10000000006016",
    "fileId": "10000000006016",
    "fileItemId" : "10000000006016",
    "name" : "/",
    "fileItemName" : "/",
    "suffix" : null,
    "length" : 0,
    "projectId" : "10000000006016",
    "parentId" : null,
    "folder" : true,
    "storeId" : null,
    "version" : 1,
    "status" : "success",
    "uploadMode" : null,
    "md5" : null,
    "physicalIndex" : null,
    "updateTime" : "2022-02-02 02:02:02",
    "current": true,
    "path" : "/",
    "originalCreateTime": "2022-02-02 02:02:02",
  },
  "message" : null
}

4. 创建文件夹

在第2步中，您获取了将要存储文件的项目（Project），请记住该项目的id字段(10000000006016)。

这一步将介绍如何在指定项目下创建文件夹，使用的接口为指定目录下创建文件夹 (opens new window)，您可以将文件分类上传至不同文件夹中；您也可以跳过这一步，不创建文件夹，直接在项目下创建文件项。

HTTP请求示例

请求 path

POST https://api.bimface.com/bdfs/data/v1/projects/10000000006016/folders

请求 header

"Authorization: Bearer cn-e9725999-0b36-4c0e-bdca-38ea88888888"

请求 body

{
  "autoRename" : false,
  "name" : "BIMFACE文件夹",
  "parentId" : "10000000006016",
}

HTTP响应示例

响应 200

{
  "code" : "success",
  "data" : {
    "appKey" : "odatvZYUSAWMbdUjTU8HoZXB9tFt6123",
    "createTime" : "2022-02-02 02:02:02",
    "id": "1938888813662976",
    "fileId": "1938888813662976",
    "fileItemId" : "1938888813662976",
    "name" : "BIMFACE文件夹",
    "fileItemName": "BIMFACE文件夹",
    "suffix" : null,
    "length" : 0,
    "projectId" : "10000000006016",
    "parentId" : "10000000006016",
    "folder" : true,
    "storeId" : null,
    "version" : 1,
    "status" : "success",
    "uploadMode" : null,
    "md5" : null,
    "physicalIndex" : null,
    "updateTime" : "2022-02-02 02:02:02",
    "current": true,
    "originalCreateTime": "2022-02-02 02:02:02"      
  },
  "message" : "success"
}

5. 创建文件项

在上一步中您创建了文件夹（Folder）用于分类存放文件，请记住您要存放的文件夹“BIMFACE文件夹”的ID，文件夹ID为1938888813662976，上传普通文件流 (opens new window)的接口需要folderId来明确文件存放的位置。

在创建文件项的接口中，您可以根据实际情况，填写parentId，若文件存放在文件夹中，则parentId处需填入文件夹ID(folderId)；若文件直接存放在项目下，则parentId处需填入项目ID（projectId）或根文件夹ID。

本节将介绍使用文件管理服务进行文件上传的两种方法：普通文件流上传及指定外部文件url方式上传。除此之外，BIMFACE还支持追加上传 (opens new window)和分片上传 (opens new window)，主要解决大文件上传，或者网络环境较差时的上传问题，具体方法请参见相关接口文档。

• 普通文件流上传

需要上传的文件在本地，可使用普通文件流上传。

HTTP请求示例

请求 path

POST https://api.bimface.com/bdfs/data/v1/projects/10000000006016/fileItems?length=345345345&name=sample.rvt&parentId=1938888813662976

请求 header

"Authorization: Bearer cn-e9725999-0b36-4c0e-bdca-38ea88888888"

HTTP响应示例

响应 200

{
  "code" : "success",
  "data" : {
    "appKey" : "odatvZYUSAWMbdUjTU8HoZXB9tFt6123",
    "createTime" : "2022-02-02 02:02:02",
    "id": "10000022400001",
    "fileId": "10000022400001",
    "fileItemId" : "10000022400001",
    "name": "sample.rvt",
    "fileItemName": "sample.rvt",
    "suffix" : "rvt",
    "length" : 345345345,
    "projectId" : "10000000006016",
    "parentId" : "1938888813662976",
    "folder" : false,
    "storeId" : "10000000021156",
    "version" : 1,
    "status" : "success",
    "uploadMode" : "GENERAL",  
    "md5" : "sdfhskbvnksdiuewriusbndskudf",
    "physicalIndex" : "a72eaf22f4214a6384429f78b690c983",
    "updateTime" : "2022-02-02 02:02:02",
    "current": true,
    "originalCreateTime": "2022-02-02 02:02:02"
  },
  "message" : "success"
}

• 指定外部文件url方式上传

如果需要上传的文件不在本地，且该文件可以通过HTTP协议的URL进行下载，BIMFACE支持传入该文件的URL，自动进行下载并完成文件上传，无须用户先下载，再上传。

HTTP请求示例

请求 path

POST https://api.bimface.com/bdfs/data/v1/projects/10000000006016/fileItems/sourceUrl?name=sample.rvt&url=https://static.bimface.com/attach/cccc1d004e66a98569c7963a077d_sample.rvt&parentId=1938888813662976

请求 header

"Authorization: Bearer cn-e9725999-0b36-4c0e-bdca-38ea88888888"

HTTP响应示例

响应 200

{
  "code" : "success",
  "data" : {
    "appKey" : "odatvZYUSAWMbdUjTU8HoZXB9tFt6123",
    "createTime" : "2022-02-02 02:02:02",
    "id": "10000022400001",
    "fileId": "10000022400001",
    "fileItemId" : "10000022400001",
    "name": "sample.rvt",
    "fileItemName": "sample.rvt",
    "suffix" : "rvt",
    "length" : 345345345,
    "projectId" : "10000000006016",
    "parentId" : "1938888813662976",
    "folder" : false,
    "storeId" : "10000000021156",
    "version" : 1,
    "status" : "success",
    "uploadMode" : "GENERAL",  
    "md5" : "sdfhskbvnksdiuewriusbndskudf",
    "physicalIndex" : "a72eaf22f4214a6384429f78b690c983",
    "updateTime" : "2022-02-02 02:02:02",
    "current": true,
    "originalCreateTime": "2022-02-02 02:02:02"
  },
  "message" : "success"
}