C#二次開發BIMFACE系列61 File Management檔案管理服務介面二次開發及實戰詳解

張傳寧發表於2022-04-18

系列目錄【已更新最新開發文章，點選檢視詳細】

　　在我的部落格《C#二次開發BIMFACE系列61 File Management檔案管理服務介面二次開發及實戰詳解》最後列出了 File Management 的介面，本篇主要介紹對該介面的封裝及Demo程式。

本篇內容對應的視訊教程《BIMFACE二次開發系列11.2 File Management介面二次開發及實戰詳解》

B站：https://www.bilibili.com/video/BV1Ei4y1U7k7

頭條：https://www.ixigua.com/7087537345448116776

File Management 相關名稱解釋

　　檔案管理File Management API由以下基本型別構成，熟悉以下名詞，以便更好的理解 File Management 模組

以上幾種儲存型別之間存在關聯關係，層級關係如下所示：

需要通過Hub導航到Project，每個使用者的Project都隸屬於某個廣聯達產品的儲存中心（hub）；
Folder隸屬於Project，也可以把Project看做一個根資料夾;
FileItem為儲存資料的基本單元，可以位於Folder下一層級，也可以和Folder同一層級。

訪問金鑰（Access Token）

Access Token代表了使用者當前應用的身份，使用者可以通過Access Token對自己應用內的檔案發起檔案上傳、下載、刪除、更新等操作，同時也能訪問所有BIMFACE的服務端資料介面進行輕量化和資料服務等操作。因此，獲取AccessToken是程式開發的第一步，更多關於Access Token的說明可參考Access Token

錯誤碼

當使用者訪問File Management API出現錯誤時，File Management將返回給使用者一個HTTP狀態碼，錯誤原因將在響應正文中返回，便於使用者定位問題。

以下是伴隨HTTP 404的錯誤碼響應示例。

{
    "timestamp": 1646985853402,
    "status": 404,
    "error": "Not Found",
    "message": "",
    "path": "/bdfs/v1/projects/10000000006016/folders/10000000006017/parent"
}

術語表

C#二次開發BIMFACE系列61 File Management檔案管理服務介面二次開發及實戰詳解

File Management API封裝

在我的開源專案《BIMFACE.SDK.CSharp》中封裝了54個File Management 介面的同步與非同步方法，如下圖

這裡列出幾個核心介面的封裝程式碼

獲取Hub列表

 1 /// <summary>
 2 /// 獲取Hub列表
 3 /// <para>通過該介面可查詢您的賬號已註冊哪些儲存中心（Hub）,您可以將檔案上傳到已註冊的儲存空間裡。</para>
 4 /// </summary>
 5 /// <param name="accessToken">【必填】令牌</param>
 6 /// <param name="dateTimeFrom">【選填】開始時間，篩選時間範圍內建立的Hub，格式為：yyyy-MM-dd HH:mm:ss</param>
 7 /// <param name="dateTimeTo">【選填】終止時間，篩選時間範圍內建立的Hub，格式為：yyyy-MM-dd HH:mm:ss</param>
 8 /// <param name="info">【選填】描述資訊</param>
 9 /// <param name="name">【選填】Hub名稱</param>
10 /// <param name="tenantCode">【選填】產品所屬的租戶 (預設值:"BIMFACE")</param>
11 /// <returns></returns>
12 /// <exception cref="BIMFaceException"></exception>
13 public virtual HubsResponse GetHubs(string accessToken, string dateTimeFrom = "", string dateTimeTo = "", string info = "", string name = "", string tenantCode = "BIMFACE")
14 {
15     /*官方文件：https://bimface.com/docs/file-management/v1/api-reference/getHubListUsingGET.html */
16 
17     //GET https://api.bimface.com/bdfs/domain/v1/hubs
18     string url = BIMFaceConstants.API_HOST + "/bdfs/domain/v1/hubs?1=1";
19     if (!string.IsNullOrWhiteSpace(dateTimeFrom))
20     {
21         url += "&dateTimeFrom=" + dateTimeFrom;
22     }
23     if (!string.IsNullOrWhiteSpace(dateTimeTo))
24     {
25         url += "&dateTimeTo=" + dateTimeTo;
26     }
27     if (!string.IsNullOrWhiteSpace(info))
28     {
29         url += "&info=" + info;
30     }
31     if (!string.IsNullOrWhiteSpace(name))
32     {
33         url += "&name=" + name;
34     }
35     if (!string.IsNullOrWhiteSpace(tenantCode))
36     {
37         url += "&tenantCode=" + tenantCode;
38     }
39 
40     BIMFaceHttpHeaders headers = new BIMFaceHttpHeaders();
41     headers.AddOAuth2Header(accessToken);
42 
43     try
44     {
45         HubsResponse response;
46 
47         HttpManager httpManager = new HttpManager(headers);
48         HttpResult httpResult = httpManager.Get(url);
49         if (httpResult.Status == HttpResult.STATUS_SUCCESS)
50         {
51             response = httpResult.Text.DeserializeJsonToObject<HubsResponse>();
52         }
53         else
54         {
55             response = new HubsResponse
56             {
57                 Message = httpResult.RefText
58             };
59         }
60 
61         return response;
62     }
63     catch (Exception ex)
64     {
65         throw new BIMFaceException("[獲取Hubs]發生異常！", ex);
66     }
67 }

View Code

建立專案

 1 /// <summary>
 2 /// 建立專案
 3 /// <para>用Access Token建立專案,對檔案分專案進行管理，建立專案之前需要獲取應用所屬的hubId。</para>
 4 /// </summary>
 5 /// <param name="accessToken">【必填】令牌</param>
 6 /// <param name="hubId">【必填】hub編號</param>
 7 /// <param name="projectName">【必填】專案名稱</param>
 8 /// <param name="projectInfo">【選填】專案描述，最多255個字元</param>
 9 /// <param name="projectThumbnail">【選填】專案縮圖url</param>
10 /// <returns></returns>
11 /// <exception cref="BIMFaceException"></exception>
12 public virtual ProjectResponse CreateProject(string accessToken, string hubId, string projectName, string projectInfo = null, string projectThumbnail = null)
13 {
14     /*官方文件：https://bimface.com/docs/file-management/v1/api-reference/createProjectUsingPOST.html */
15 
16     //POST https://api.bimface.com/bdfs/domain/v1/hubs/{hubId}/projects
17     string url = string.Format(BIMFaceConstants.API_HOST + "/bdfs/domain/v1/hubs/{0}/projects", hubId);
18 
19     string data = new ProjectSaveRequest
20     {
21         Name = projectName,
22         Thumbnail = projectThumbnail,
23         Info = projectInfo
24     }.SerializeToJson();
25 
26     BIMFaceHttpHeaders headers = new BIMFaceHttpHeaders();
27     headers.AddOAuth2Header(accessToken);
28 
29     try
30     {
31         ProjectResponse response;
32 
33         HttpManager httpManager = new HttpManager(headers);
34         HttpResult httpResult = httpManager.Post(url, data);
35         if (httpResult.Status == HttpResult.STATUS_SUCCESS)
36         {
37             response = httpResult.Text.DeserializeJsonToObject<ProjectResponse>();
38         }
39         else
40         {
41             response = new ProjectResponse
42             {
43                 Message = httpResult.RefText
44             };
45         }
46 
47         return response;
48     }
49     catch (Exception ex)
50     {
51         throw new BIMFaceException("[建立專案資訊]發生異常！", ex);
52     }
53 }

View Code

指定目錄下建立資料夾

 1 /// <summary>
 2 /// 指定目錄下建立資料夾
 3 /// <para>在指定的位置建立資料夾，可對檔案進行分類管理。需要獲取所屬的專案Id，以及資料夾所在位置的上層檔案Id或檔案路徑，兩個引數必須二選一填入。</para>
 4 /// </summary>
 5 /// <param name="accessToken">【必填】令牌</param>
 6 /// <param name="projectId">【必填】</param>
 7 /// <param name="folderName">【必填】 資料夾名稱</param>
 8 /// <param name="parentPath">【必填】父目錄檔案路徑,parentId和parentPath,必須二選一填入</param>
 9 /// <param name="parentId">【必填】父目錄檔案ID,parentId和parentPath,必須二選一填入</param>
10 /// <param name="autoRename">【選填】當存在同名資料夾時,是否重新命名（預設false，false情況下有同名資料夾則報錯）</param>
11 /// <returns></returns>
12 /// <exception cref="BIMFaceException"></exception>
13 public virtual FolderResponse CreateFolder(string accessToken, string projectId, string folderName, string parentPath, string parentId, bool? autoRename = null)
14 {
15     /* 官方文件：https://bimface.com/docs/file-management/v1/api-reference/createFolderUsingPOST.html */
16 
17     //POST https://api.bimface.com/bdfs/data/v1/projects/{projectId}/folders
18     string url = string.Format(BIMFaceConstants.API_HOST + "/bdfs/data/v1/projects/{0}/folders", projectId);
19     string data = new FolderCreateRequest
20     {
21         Name = folderName,
22         ParentPath = parentPath,
23         ParentId = parentId,
24         AutoRename = autoRename
25     }.SerializeToJson();
26 
27     BIMFaceHttpHeaders headers = new BIMFaceHttpHeaders();
28     headers.AddOAuth2Header(accessToken);
29 
30     try
31     {
32         FolderResponse response;
33 
34         HttpManager httpManager = new HttpManager(headers);
35         HttpResult httpResult = httpManager.Post(url,data);
36         if (httpResult.Status == HttpResult.STATUS_SUCCESS)
37         {
38             response = httpResult.Text.DeserializeJsonToObject<FolderResponse>();
39         }
40         else
41         {
42             response = new FolderResponse
43             {
44                 Message = httpResult.RefText
45             };
46         }
47 
48         return response;
49     }
50     catch (Exception ex)
51     {
52         throw new BIMFaceException("[建立資料夾資訊]發生異常！", ex);
53     }
54 }

View Code

上傳檔案(普通檔案流方式)

 1 /// <summary>
 2 ///  普通檔案流上傳檔案【使用BIMFACE公有云時不推薦使用該方式。推薦使用檔案直傳 UploadFileByPolicy()方法，效率更高】。
 3 /// <para>使用普通檔案流上傳，檔案流需要在request body中傳遞。</para>
 4 /// </summary>
 5 /// <param name="accessToken">【必填】令牌</param>
 6 /// <param name="projectId">【必填】專案ID</param>
 7 /// <param name="fileName">【必填】檔案的名稱(不包含路徑)</param>
 8 /// <param name="fileStream">【必填】檔案流</param>
 9 /// <param name="parentId">【必填】父資料夾Id，parentId和parentPath必須二選一填入</param>
10 /// <param name="parentPath">【必填】父資料夾路徑，parentId和parentPath必須二選一填入</param>
11 /// <param name="autoRename">【可選】當存在同名檔案時,是否自動重新命名，預設為false </param>
12 /// <param name="sourceId">【可選】呼叫方的檔案源ID，不能重複</param>
13 /// <returns></returns>
14 public virtual FileUpload2Response UploadFileByStream(string accessToken, string projectId, string fileName, Stream fileStream, string parentId, string parentPath, bool? autoRename = null, string sourceId = "")
15 {
16     /* 官方文件：https://bimface.com/docs/file-management/v1/api-reference/uploadFileItemUsingPOST.html */
17 
18     /* 此API詳解，參考作者部落格：《C#開發BIMFACE系列4 服務端API之源上傳檔案》 https://www.cnblogs.com/SavionZhang/p/11425804.html */
19 
20     /* 重要提示：使用普通檔案流上傳，不支援表單方式; 檔案流需要在 request body 中傳遞 */
21 
22     byte[] fileBytes = fileStream.ToByteArray();
23 
24     //POST https://api.bimface.com/bdfs/data/v1/projects/{projectId}/fileItems
25     string url = string.Format(BIMFaceConstants.API_HOST + "/bdfs/data/v1/projects/{0}/fileItems", projectId);
26     url = url + "?name=" + fileName.UrlEncode(Encoding.UTF8); // 使用URL編碼（UTF-8）
27     if (!string.IsNullOrEmpty(parentId))
28     {
29         url = url + "&parentId=" + parentId;
30     }
31     if (!string.IsNullOrEmpty(parentPath))
32     {
33         url = url + "&parentPath=" + parentPath;
34     }
35 
36     url = url + "&length=" + fileBytes.Length;
37 
38     if (autoRename.HasValue)
39     {
40         url = url + "&autoRename=" + autoRename.Value;
41     }
42     if (!string.IsNullOrEmpty(sourceId))
43     {
44         url = url + "&sourceId=" + sourceId;
45     }
46 
47     BIMFaceHttpHeaders headers = new BIMFaceHttpHeaders();
48     headers.AddOAuth2Header(accessToken);
49 
50     try
51     {
52         FileUpload2Response response;
53 
54         HttpManager httpManager = new HttpManager(headers);
55         HttpResult httpResult = httpManager.UploadData(url, fileBytes, WebRequestMethods.Http.Post);
56         if (httpResult.Status == HttpResult.STATUS_SUCCESS)
57         {
58             response = httpResult.Text.DeserializeJsonToObject<FileUpload2Response>();
59         }
60         else
61         {
62             response = new FileUpload2Response
63             {
64                 Message = httpResult.RefText
65             };
66         }
67 
68         return response;
69     }
70     catch (Exception ex)
71     {
72         throw new BIMFaceException("[普通檔案流上傳檔案]發生異常！", ex);
73     }
74 }

View Code

上傳檔案(外部檔案url方式)

 1 /// <summary>
 2 ///  指定外部檔案url方式上傳檔案。
 3 /// <para>如果需要上傳的檔案不在本地，且該檔案可以通過指定的HTTP URL可以下載，BIMFACE支援直接傳一個外部的HTTP檔案URL，BIMFACE會去下載該檔案，而無須使用者先下載再上傳。</para>
 4 /// </summary>
 5 /// <param name="accessToken">【必填】令牌</param>
 6 /// <param name="projectId">【必填】專案ID</param>
 7 /// <param name="fileName">【必填】檔案的名稱(不包含路徑)</param>
 8 /// <param name="parentId">【必填】父資料夾Id，parentId和parentPath必須二選一填入</param>
 9 /// <param name="parentPath">【必填】父資料夾路徑，parentId和parentPath必須二選一填入</param>
10 /// <param name="fileUrl">【必填】外部檔案的url地址</param>
11 /// <param name="autoRename">【可選】當存在同名檔案時,是否自動重新命名，預設為false </param>
12 /// <param name="sourceId">【可選】呼叫方的檔案源ID，不能重複</param>
13 /// <param name="etag">【可選】檔案etag</param>
14 /// <param name="maxLength">【可選】</param>
15 /// <returns></returns>
16 public virtual FileUpload2Response UploadFileByUrl(string accessToken, string projectId, string fileName, string parentId, string parentPath, string fileUrl, bool? autoRename = null, string sourceId = "", string etag = "", long? maxLength = null)
17 {
18     /* 官方文件：https://bimface.com/docs/file-management/v1/api-reference/uploadByUrlUsingPOST.html */
19 
20     /* 此API詳解，參考作者部落格：《C#開發BIMFACE系列4 服務端API之源上傳檔案》 https://www.cnblogs.com/SavionZhang/p/11425804.html */
21 
22     /* 如果需要上傳的檔案不在本地，且該檔案可以通過指定的HTTP URL可以下載，BIMFACE支援直接傳一個外部的HTTP檔案URL, BIMFACE會去下載該檔案，而無須使用者先下載，再上傳。 */
23 
24     //POST https://api.bimface.com/bdfs/data/v1/projects/{projectId}/fileItems/sourceUrl
25     string url = string.Format(BIMFaceConstants.API_HOST + "/bdfs/data/v1/projects/{0}/fileItems/sourceUrl", projectId);
26     url = url + "?name=" + fileName.UrlEncode(Encoding.UTF8); // 使用URL編碼（UTF-8）
27 
28     if (!string.IsNullOrWhiteSpace(parentId))
29     {
30         url = url + "&parentId=" + parentId;
31     }
32     if (!string.IsNullOrWhiteSpace(parentPath))
33     {
34         url = url + "&parentPath=" + parentPath;
35     }
36 
37     url = url + "&url=" + fileUrl.UriEscapeDataString();
38 
39     if (autoRename.HasValue)
40     {
41         url = url + "&autoRename=" + autoRename.Value;
42     }
43     if (!string.IsNullOrWhiteSpace(etag))
44     {
45         url = url + "&etag=" + etag;
46     }
47     if (maxLength.HasValue)
48     {
49         url = url + "&maxLength=" + maxLength.Value;
50     }
51     if (!string.IsNullOrWhiteSpace(sourceId))
52     {
53         url = url + "&sourceId=" + sourceId;
54     }
55 
56     BIMFaceHttpHeaders headers = new BIMFaceHttpHeaders();
57     headers.AddOAuth2Header(accessToken);
58 
59     try
60     {
61         FileUpload2Response response;
62 
63         HttpManager httpManager = new HttpManager(headers);
64         HttpResult httpResult = httpManager.Post(url);
65         if (httpResult.Status == HttpResult.STATUS_SUCCESS)
66         {
67             response = httpResult.Text.DeserializeJsonToObject<FileUpload2Response>();
68         }
69         else
70         {
71             response = new FileUpload2Response
72             {
73                 Message = httpResult.RefText
74             };
75         }
76 
77         return response;
78     }
79     catch (Exception ex)
80     {
81         throw new BIMFaceException("[指定外部檔案url方式上傳檔案]發生異常！", ex);
82     }
83 }

View Code

上傳檔案(檔案直傳)

 1 /// <summary>
 2 ///  【推薦使用該方式】根據policy憑證在web端上傳檔案。
 3 /// <para>通過介面獲取檔案直傳的policy憑證後，可以直接在前端使用表單上傳方式將檔案上傳到BIMFACE的物件儲存上。</para>
 4 /// <para>特別提醒：BIMFACE公有云支援檔案直傳。私有化部署時使用的物件儲存是 MinIO，不支援 Policy 上傳。使用普通檔案流上傳 或者 指定外部檔案URL方式上傳。</para>
 5 /// </summary>
 6 /// <param name="accessToken">【必填】令牌</param>
 7 ///  <param name="projectId">【必填】專案ID</param>
 8 /// <param name="fileFullName">【必填】待上傳的檔案(包含全路徑的完全限定名)</param>
 9 /// <param name="parentId">【必填】父資料夾Id，parentId和parentPath必須二選一填入</param>
10 /// <param name="parentPath">【必填】父資料夾路徑，parentId和parentPath必須二選一填入</param>
11 /// <param name="autoRename">【可選】當存在同名檔案時,是否自動重新命名，預設為false </param>
12 /// <param name="sourceId">【可選】呼叫方的檔案源ID，不能重複</param>
13 /// <param name="maxLength">【可選】</param>
14 /// <returns></returns>
15 public virtual FileUpload2Response UploadFileByPolicy(string accessToken, string projectId, string fileFullName, string parentId, string parentPath, bool? autoRename = null, string sourceId = "", long? maxLength = null)
16 {
17     /* 官方文件：https://bimface.com/docs/file-management/v1/api-reference/uploadByPolicyUsingPOST.html */
18     /* 此API詳解，參考作者部落格：《C#開發BIMFACE系列5 服務端API之檔案直傳》 https://www.cnblogs.com/SavionZhang/p/11425945.html */
19 
20     /* BIMFACE使用了分散式物件儲存來儲存使用者上傳的模型/圖紙檔案。
21        如使用普通的檔案上傳介面，檔案流會通過BIMFACE的伺服器，再流向最終的分散式儲存系統，整個上傳過程會受BIMFACE伺服器的頻寬限制，上傳速度非最優。 
22        如使用檔案直傳介面，開發者應用在申請到一個Policy憑證後，可以直接上傳檔案跟BIMFACE後臺的分散式儲存系統， 
23        這樣上傳速度和穩定性都會有提升，是我們推薦的上傳方式。 
24     */
25 
26     /* 使用流程如下：
27         1、開發者應用向BIMFACE申請上傳Policy請求。
28         2、BIMFACE返回上傳Policy和簽名給開發者應用。
29         3、開發者應用使用在第二個步驟中獲取的URL資訊，直接上傳檔案資料到BIMFACE後端的分散式物件儲存。
30      */
31 
32     FileUpload2Response response = null;
33     try
34     {
35         string fileName = new FileInfo(fileFullName).Name;
36 
37         FileUploadPolicyResponse policyResponse = GetFileUploadPolicy(accessToken, projectId, fileName, parentId, parentPath, autoRename, sourceId, maxLength);
38         if (policyResponse.Code == HttpResult.STATUS_SUCCESS)
39         {
40             /* 官方文件 https://bimface.com/docs/file-management/v1/api-reference/getFilePolicyUsingGET.html
41              * 中說明該介面的請求地址為：POST https://api.bimface.com/bdfs/data/v1/projects/policy
42              *
43              *  經測試
44              * （1）使用該地址在postman中測試可以成功。但是使用本程式測試失敗，提示 unauthorized。Full authentication is required to access this resource。
45              * （2）使用“獲取檔案直傳的policy憑證”介面中返回的 host 地址(https://bf-prod-srcfile.oss-cn-beijing.aliyuncs.com)，本程式測試成功。
46              */
47 
48             //string url = BIMFaceConstants.API_HOST + "/bdfs/data/v1/projects/policy";
49             string url = policyResponse.Data.Host;
50 
51             /* C# 語言 Dictionary 字典中 key 是關鍵字，不能新增進去。所以統一新增了響應的字尾 _BIMFACE_，解析時再去除字尾 */
52             NameValueCollection kVDatas = new NameValueCollection();
53             kVDatas.Add("name" + StringUtils.Symbol.KEY_SUFFIX, fileName);
54             kVDatas.Add("key" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.ObjectKey);
55             kVDatas.Add("policy" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.Policy);
56             kVDatas.Add("OSSAccessKeyId" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.AccessId);
57             kVDatas.Add("success_action_status" + StringUtils.Symbol.KEY_SUFFIX, "200");
58             kVDatas.Add("callback" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.CallbackBody);
59             kVDatas.Add("signature" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.Signature);
60 
61             BIMFaceHttpHeaders headers = new BIMFaceHttpHeaders();
62             headers.AddOAuth2Header(accessToken);
63 
64             HttpManager httpManager = new HttpManager(headers);
65             HttpResult httpResult = httpManager.UploadFormByMultipart(url, fileFullName, kVDatas);
66             if (httpResult.Status == HttpResult.STATUS_SUCCESS)
67             {
68                 response = httpResult.Text.DeserializeJsonToObject<FileUpload2Response>();
69             }
70             else
71             {
72                 response = new FileUpload2Response
73                 {
74                     Message = httpResult.RefText
75                 };
76             }
77         }
78 
79         return response;
80     }
81     catch (Exception ex)
82     {
83         throw new BIMFaceException("[通過檔案直傳的policy憑證，直接上傳檔案時]發生異常！", ex);
84     }
85 }