C#开发BIMFACE系列5 服务端API之文件直传

系列目录     【已更新最新开发文章，点击查看详细】

BIMFACE使用了分布式对象存储来存储用户上传的模型/图纸文件。如使用普通的文件上传接口， 文件流会通过BIMFACE的服务器，再流向最终的分布式存储系统，整个上传过程会受BIMFACE服务器的带宽限制，上传速度非最优。 如使用文件直传接口，开发者应用在申请到一个Policy凭证后，可以直接上传文件跟BIMFACE后台的分布式存储系统， 这样上传速度和稳定性都会有提升，是我们推荐的上传方式。

另外，很多BIMFACE应用都有自己的Web前端页面，这种情况我们也推荐使用文件直传接口。

文件直传的逻辑图如下：

使用流程如下：

1. 开发者应用向 BIMFACE 申请上传 Policy 请求。

2. BIMFACE 返回上传 Policy 和签名给开发者应用。

3. 开发者应用使用在第二个步骤中获取的 URL 信息，直接上传文件数据到 BIMFACE 后端的分布式对象存储。

步骤一：获取文件直传的policy凭证

请求地址：GET https://file.bimface.com/upload/policy

请求参数：

请求 path(示例)：https://file.bimface.com/upload/policy?name=example.rvt

请求 header(示例)："Authorization: Bearer dc671840-bacc-4dc5-a134-97c1918d664b"

HTTP响应示例(200)：

C#实现方法：application/octet-stream

 /// <summary>
 ///  获取文件直传的policy凭证
 /// </summary>
 /// <param name="accessToken">令牌</param>
 /// <param name="fileName">【必填】文件的全名</param>
 /// <param name="sourceId">【可选】调用方的文件源ID，不能重复</param>
 /// <returns></returns>
 public virtual FileUploadPolicyResponse GetFileUploadPolicy(string accessToken, string fileName, string sourceId = "")
 {
     /*  BIMFACE 使用了分布式对象存储来存储用户上传的模型/图纸文件。
         如使用普通的文件上传接口，文件流会通过BIMFACE的服务器，再流向最终的分布式存储系统，整个上传过程会受BIMFACE服务器的带宽限制，上传速度非最优。
         如使用文件直传接口，开发者应用在申请到一个Policy凭证后，可以直接上传文件跟BIMFACE后台的分布式存储系统，
         这样上传速度和稳定性都会有提升，是我们推荐的上传方式。
      */

     /* 使用流程如下：
         1、开发者应用向BIMFACE申请上传Policy请求
         2、BIMFACE返回上传Policy和签名给开发者应用。
      */

     //GET https://file.bimface.com/upload/policy 。例如：https://file.bimface.com/upload/policy?name=example.rvt
     string url = string.Format(BimfaceConstants.FILE_HOST + "/upload/policy?name={0}", fileName.UrlEncode(Encoding.UTF8)); //文件的全名，使用URL编码（UTF-8），最多256个字符
     if (sourceId.IsNotNullAndWhiteSpace())
     {
         url = url + "&sourceId=" + sourceId;
     }

     BimFaceHttpHeaders headers = new BimFaceHttpHeaders();
     headers.AddOAuth2Header(accessToken);

     try
     {
         FileUploadPolicyResponse response;

         HttpManager httpManager = new HttpManager(headers);
         HttpResult httpResult = httpManager.Get(url);
         if (httpResult.Status == HttpResult.STATUS_SUCCESS)
         {
             response = httpResult.Text.DeserializeJsonToObject<FileUploadPolicyResponse>();
         }
         else
         {
             response = new FileUploadPolicyResponse
             {
                 Message = httpResult.RefText
             };
         }

         return response;
     }
     catch (Exception ex)
     {
         throw new Exception("获取文件直传的policy凭证时发生异常！", ex);
     }
 }

其中引用的 httpManager.Get() 方法如下：

 /// <summary>
 /// HTTP-GET方法，(不包含body数据)。
 /// 发送 HTTP 请求并返回来自 Internet 资源的响应(HTML代码)
 /// </summary>
 /// <param name="url">请求目标URL</param>
 /// <returns>HTTP-GET的响应结果</returns>
 public HttpResult Get(string url)
 {
     return RequestString(url, null, WebRequestMethods.Http.Get, null);
 }

 /// <summary>
 ///  HTTP请求(包含文本的body数据)
 /// </summary>
 /// <param name="url">请求目标URL</param>
 /// <param name="data">主体数据(普通文本或者JSON文本)。如果参数中有中文，请使用合适的编码方式进行编码，例如：gb2312或者utf-8</param>
 /// <param name="method">请求的方法。请使用 WebRequestMethods.Http 的枚举值</param>
 /// <param name="contentType"><see langword="Content-type" /> HTTP 标头的值。请使用 ContentType 类的常量来获取</param>
 /// <returns></returns>
 private HttpResult RequestString(string url, string data, string method, string contentType)
 {
     HttpResult httpResult = new HttpResult();
     HttpWebRequest httpWebRequest = null;

     try
     {
         httpWebRequest = WebRequest.Create(url) as HttpWebRequest;
         httpWebRequest.Method = method;
         httpWebRequest.Headers = HeaderCollection;
         httpWebRequest.CookieContainer = CookieContainer;
         if (!string.IsNullOrWhiteSpace(contentType))
         {
             httpWebRequest.ContentType = contentType;// 此属性的值存储在WebHeaderCollection中。如果设置了WebHeaderCollection，则属性值将丢失。所以放置在Headers 属性之后设置
         }
         httpWebRequest.UserAgent = _userAgent;
         httpWebRequest.AllowAutoRedirect = _allowAutoRedirect;
         httpWebRequest.ServicePoint.Expect100Continue = false;

         if (data != null)
         {
             httpWebRequest.AllowWriteStreamBuffering = true;
             using (Stream requestStream = httpWebRequest.GetRequestStream())
             {
                 requestStream.Write(EncodingType.GetBytes(data), , data.Length);//将请求参数写入请求流中
                 requestStream.Flush();
             }
         }

         HttpWebResponse httpWebResponse = httpWebRequest.GetResponse() as HttpWebResponse;
         if (httpWebResponse != null)
         {
             GetResponse(ref httpResult, httpWebResponse);
             httpWebResponse.Close();
         }
     }
     catch (WebException webException)
     {
         GetWebExceptionResponse(ref httpResult, webException);
     }
     catch (Exception ex)
     {
         GetExceptionResponse(ref httpResult, ex, method, contentType);
     }
     finally
     {
         if (httpWebRequest != null)
         {
             httpWebRequest.Abort();
         }
     }

     return httpResult;
 }

步骤二：根据policy凭证在web端上传文件

通过接口“https://file.bimface.com/upload/policy”获取文件直传的policy凭证后，可以直接在前端使用表单上传方式将文件上传到BIMFACE的对象存储上。

BIMFACE 控制台就是通过这种方式来实现文件上传的，可以F12→network查看请求详情。Form Data 数据格式如下：

 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="key"

 847adf52871d4c25a23424942f7f4c1d
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="policy"

 eyJleHBpcmF0aW9uIjoiMjAxOS0wOC0yOFQxMjo1MjoyMi4wMjVaIiwiY29uZGl0aW9ucyI6W1siY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsMTA3Mzc0MTgyNF0seyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDAifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIiJdXX0=
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="OSSAccessKeyId"

 5nGlEwOIzrwCVaDZ
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="success_action_status"

 200
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="callback"

 eyJjYWxsYmFja1VybCI6Imh0dHBzOi8vZmlsZS5iaW1mYWNlLmNvbS9vc3MvcmVjZWl2ZSIsImNhbGxiYWNrSG9zdCI6ImZpbGUuYmltZmFjZS5jb20iLCJjYWxsYmFja0JvZHkiOiJvYmplY3RcdTAwM2Qke29iamVjdH1cdTAwMjZzaXplXHUwMDNkJHtzaXplfVx1MDAyNmV0YWdcdTAwM2Qke2V0YWd9XHUwMDI2bmFtZVx1MDAzZDAxX0JJTUZBQ0UlRTclQTQlQkElRTQlQkUlOEIlRTYlOTYlODclRTQlQkIlQjYtUmV2aXQlRTYlQTglQTElRTUlOUUlOEIucnZ0XHUwMDI2ZmlsZUlkXHUwMDNkMTY4MTM0ODIwMDAyMzUyMFx1MDAyNmFwcGtleVx1MDAzZEh0em92SmdpQWxWNkZvOVczbnZ3eW1zb2NZNXc5c0pSXHUwMDI2c291cmNlSWRcdTAwM2Q1ODNlMWNkOWJiNzc0YTdjOGNhMzlhN2I3YzJlZDEwOFx1MDAyNmZpbGVCdWNrZXRcdTAwM2RiZi1wcm9kLXNyY2ZpbGUiLCJjYWxsYmFja0JvZHlUeXBlIjoiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIn0=
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="signature"

 /njtosIn/4EkOWqpVNW/8Dlu73E=
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="id"

 WU_FILE_0
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="name"

 01_BIMFACE示例文件-Revit模型.rvt
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="type"

 application/octet-stream
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="lastModifiedDate"

 Thu Aug 01 2019 17:06:54 GMT+0800 (中国标准时间)
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="size"

 6459392
 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU
 Content-Disposition: form-data; name="file"; filename="01_BIMFACE示例文件-Revit模型.rvt"
 Content-Type: application/octet-stream

 ------WebKitFormBoundaryBSvYqSMAnAcFeGAU--

以获取到的policy凭证为以下数据示例：

通过表单方式上传时，请求的构造方式为：

请求示例：使用Postman测试上传到BIMFACE的后台即阿里云服务器

Postman 给出的 HTTP 的multipart/form-data 的数据格式并不正确。

关于 multipart/form-data 的正确的数据格式请参考：

C# HTTP系列 HttpWebRequest 与 HttpWebResponse

C# HTTP系列13 以form-data方式上传多个文件以及键值对集合到远程服务器

C#实现方法：

 /// <summary>
 ///  通过文件直传的policy凭证，直接上传文件【推荐使用该方式】
 /// </summary>
 /// <param name="accessToken">令牌</param>
 /// <param name="fileFullName">【必填】待上传的文件(包含全路径的完全限定名)</param>
 /// <returns></returns>
 public FileUploadResponse UploadFileByPolicy(string accessToken, string fileFullName)
 {
     /* BIMFACE使用了分布式对象存储来存储用户上传的模型/图纸文件。
        如使用普通的文件上传接口，文件流会通过BIMFACE的服务器，再流向最终的分布式存储系统，整个上传过程会受BIMFACE服务器的带宽限制，上传速度非最优。
        如使用文件直传接口，开发者应用在申请到一个Policy凭证后，可以直接上传文件跟BIMFACE后台的分布式存储系统，
        这样上传速度和稳定性都会有提升，是我们推荐的上传方式。
     */

     /* 使用流程如下：
         1、开发者应用向BIMFACE申请上传Policy请求。
         2、BIMFACE返回上传Policy和签名给开发者应用。
         3、开发者应用使用在第二个步骤中获取的URL信息，直接上传文件数据到BIMFACE后端的分布式对象存储。
      */
     FileUploadResponse response = null;
     try
     {
         FileInfo fileInfo = new FileInfo(fileFullName);
         string fileName = fileInfo.Name;

         FileUploadPolicyResponse policyResponse = GetFileUploadPolicy(accessToken, fileName);
         if (policyResponse.Code == HttpResult.STATUS_SUCCESS)
         {
             string url = policyResponse.Data.Host;

             /* Dictionary 字典中 key 是关键字，不能添加进去。所以添加了响应的后缀 _BIMFACE_，解析时再去除后缀 */
             NameValueCollection kVDatas = new NameValueCollection();
             kVDatas.Add("name" + StringUtils.Symbol.KEY_SUFFIX, fileName);
             kVDatas.Add("key" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.ObjectKey);
             kVDatas.Add("policy" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.Policy);
             kVDatas.Add("OSSAccessKeyId" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.AccessId);
             kVDatas.Add("success_action_status" + StringUtils.Symbol.KEY_SUFFIX, "");
             kVDatas.Add("callback" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.CallbackBody);
             kVDatas.Add("signature" + StringUtils.Symbol.KEY_SUFFIX, policyResponse.Data.Signature);

             HttpManager httpManager = new HttpManager();
             HttpResult httpResult = httpManager.UploadFormByMultipart(url, fileFullName, kVDatas);
             if (httpResult.Status == HttpResult.STATUS_SUCCESS)
             {
                 response = httpResult.Text.DeserializeJsonToObject<FileUploadResponse>();
             }
             else
             {
                 response = new FileUploadResponse
                 {
                     Message = httpResult.RefText
                 };
             }
         }

         return response;
     }
     catch (Exception ex)
     {
         throw new Exception("通过文件直传的policy凭证，直接上传文件时发生异常！", ex);
     }
 }

其中引用的 httpManager.UploadFormByMultipart() 方法如下：

 /// <summary>
 /// HTTP请求(包含多分部数据,multipart/form-data)。
 /// 将文件以及多个参数以多分部数据表单方式上传到指定url的服务器
 /// </summary>
 /// <param name="url">请求目标URL</param>
 /// <param name="fileFullName">待上传的文件(包含全路径的完全限定名)</param>
 /// <param name="kVDatas">请求时表单键值对数据。</param>
 /// <param name="method">请求的方法。请使用 WebRequestMethods.Http 的枚举值</param>
 /// <param name="timeOut">获取或设置 <see cref="M:System.Net.HttpWebRequest.GetResponse" /> 和
 ///                       <see cref="M:System.Net.HttpWebRequest.GetRequestStream" /> 方法的超时值（以毫秒为单位）。
 ///                       -1 表示永不超时
 /// </param>
 /// <returns></returns>
 public HttpResult UploadFormByMultipart(string url, string fileFullName, NameValueCollection kVDatas = null, string method = WebRequestMethods.Http.Post, int timeOut = -)
 {
     string[] fileFullNames = { fileFullName };

     return UploadFormByMultipart(url, fileFullNames, kVDatas, method, timeOut);
 }

 /// <summary>
 /// HTTP请求(包含多分部数据,multipart/form-data)。
 /// 将多个文件以及多个参数以多分部数据表单方式上传到指定url的服务器
 /// </summary>
 /// <param name="url">请求目标URL</param>
 /// <param name="fileFullNames">待上传的文件列表(包含全路径的完全限定名)。如果某个文件不存在，则忽略不上传</param>
 /// <param name="kVDatas">请求时表单键值对数据。</param>
 /// <param name="method">请求的方法。请使用 WebRequestMethods.Http 的枚举值</param>
 /// <param name="timeOut">获取或设置 <see cref="M:System.Net.HttpWebRequest.GetResponse" /> 和
 ///                       <see cref="M:System.Net.HttpWebRequest.GetRequestStream" /> 方法的超时值（以毫秒为单位）。
 ///                       -1 表示永不超时
 /// </param>
 /// <returns></returns>
 public HttpResult UploadFormByMultipart(string url, string[] fileFullNames, NameValueCollection kVDatas = null, string method = WebRequestMethods.Http.Post, int timeOut = -)
 {
     #region 说明
     /* 阿里云文档：https://www.alibabacloud.com/help/zh/doc-detail/42976.htm
        C# 示例：  https://github.com/aliyun/aliyun-oss-csharp-sdk/blob/master/samples/Samples/PostPolicySample.cs?spm=a2c63.p38356.879954.18.7f3f7c34W3bR9U&file=PostPolicySample.cs
                  (C#示例中仅仅是把文件中的文本内容当做 FormData 中的项，与文件流是不一样的。本方法展示的是文件流，更通用)
       */

     /* 说明：multipart/form-data 方式提交文件
      *     (1) Header 一定要有 Content-Type: multipart/form-data; boundary={boundary}。
      *     (2) Header 和bod y之间由 \r\n--{boundary} 分割。
      *     (3) 表单域格式 ：Content-Disposition: form-data; name="{key}"\r\n\r\n
      *                   {value}\r\n
      *                   --{boundary}
      *     (4)表单域名称大小写敏感，如policy、key、file、OSSAccessKeyId、OSSAccessKeyId、Content-Disposition。
      *     (5)注意:表单域 file 必须为最后一个表单域。即必须放在最后写。
      */
     #endregion

     #region ContentType 说明
     /* 该ContentType的属性包含请求的媒体类型。分配给ContentType属性的值在请求发送Content-typeHTTP标头时替换任何现有内容。

        要清除Content-typeHTTP标头，请将ContentType属性设置为null。

      * 注意：此属性的值存储在WebHeaderCollection中。如果设置了WebHeaderCollection，则属性值将丢失。
      *      所以放置在Headers 属性之后设置
      */
     #endregion

     #region Method 说明
     /* 如果 ContentLength 属性设置为-1以外的任何值，则必须将 Method 属性设置为上载数据的协议属性。 */
     #endregion

     #region HttpWebRequest.CookieContainer 在 .NET3.5 与 .NET4.0 中的不同
     /* 请参考：https://www.crifan.com/baidu_emulate_login_for_dotnet_4_0_error_the_fisrt_two_args_should_be_string_type_0_1/ */
     #endregion

     HttpResult httpResult = new HttpResult();

     #region 校验

     if (fileFullNames == null || fileFullNames.Length == )
     {
         httpResult.Status = HttpResult.STATUS_FAIL;

         httpResult.RefCode = (int)HttpStatusCode2.USER_FILE_NOT_EXISTS;
         httpResult.RefText = HttpStatusCode2.USER_FILE_NOT_EXISTS.GetCustomAttributeDescription();

         return httpResult;
     }

     List<string> lstFiles = new List<string>();
     foreach (string fileFullName in fileFullNames)
     {
         if (File.Exists(fileFullName))
         {
             lstFiles.Add(fileFullName);
         }
     }

     if (lstFiles.Count == )
     {
         httpResult.Status = HttpResult.STATUS_FAIL;

         httpResult.RefCode = (int)HttpStatusCode2.USER_FILE_NOT_EXISTS;
         httpResult.RefText = HttpStatusCode2.USER_FILE_NOT_EXISTS.GetCustomAttributeDescription();

         return httpResult;
     }

     #endregion

     string boundary = CreateFormDataBoundary();                                         // 边界符
     byte[] beginBoundaryBytes = Encoding.UTF8.GetBytes("--" + boundary + "\r\n");     // 边界符开始。【☆】右侧必须要有 \r\n 。
     byte[] endBoundaryBytes = Encoding.UTF8.GetBytes("\r\n--" + boundary + "--\r\n"); // 边界符结束。【☆】两侧必须要有 --\r\n 。
     byte[] newLineBytes = Encoding.UTF8.GetBytes("\r\n"); //换一行
     MemoryStream memoryStream = new MemoryStream();

     HttpWebRequest httpWebRequest = null;
     try
     {
         httpWebRequest = WebRequest.Create(url) as HttpWebRequest; // 创建请求
         httpWebRequest.ContentType = string.Format(HttpContentType.MULTIPART_FORM_DATA + "; boundary={0}", boundary);
         //httpWebRequest.Referer = "http://bimface.com/user-console";
         httpWebRequest.Method = method;
         httpWebRequest.KeepAlive = true;
         httpWebRequest.Timeout = timeOut;
         httpWebRequest.UserAgent = GetUserAgent();

         #region 步骤1：写入键值对
         if (kVDatas != null)
         {
             string formDataTemplate = "Content-Disposition: form-data; name=\"{0}\"\r\n\r\n" +
                                       "{1}\r\n";

             foreach (string key in kVDatas.Keys)
             {
                 string formItem = string.Format(formDataTemplate, key.Replace(StringUtils.Symbol.KEY_SUFFIX, String.Empty), kVDatas[key]);
                 byte[] formItemBytes = Encoding.UTF8.GetBytes(formItem);

                 memoryStream.Write(beginBoundaryBytes, , beginBoundaryBytes.Length); // 1.1 写入FormData项的开始边界符
                 memoryStream.Write(formItemBytes, , formItemBytes.Length);           // 1.2 将键值对写入FormData项中
             }
         }
         #endregion

         #region 步骤2：写入文件(表单域 file 必须为最后一个表单域)

         const string filePartHeaderTemplate = "Content-Disposition: form-data; name=\"{0}\"; filename=\"{1}\"\r\n" +
                                               "Content-Type: application/octet-stream\r\n\r\n";

         int i = ;
         foreach (var fileFullName in lstFiles)
         {
             FileInfo fileInfo = new FileInfo(fileFullName);
             string fileName = fileInfo.Name;

             string fileHeaderItem = string.Format(filePartHeaderTemplate, "file", fileName);
             byte[] fileHeaderItemBytes = Encoding.UTF8.GetBytes(fileHeaderItem);

             if (i > )
             {
                 // 第一笔及第一笔之后的数据项之间要增加一个换行
                 memoryStream.Write(newLineBytes, , newLineBytes.Length);
             }
             memoryStream.Write(beginBoundaryBytes, , beginBoundaryBytes.Length);      // 2.1 写入FormData项的开始边界符
             memoryStream.Write(fileHeaderItemBytes, , fileHeaderItemBytes.Length);    // 2.2 将文件头写入FormData项中

             int bytesRead;
             byte[] buffer = new byte[];

             FileStream fileStream = new FileStream(fileFullName, FileMode.Open, FileAccess.Read);
             while ((bytesRead = fileStream.Read(buffer, , buffer.Length)) != )
             {
                 memoryStream.Write(buffer, , bytesRead);                              // 2.3 将文件流写入FormData项中
             }

             i++;
         }

         memoryStream.Write(endBoundaryBytes, , endBoundaryBytes.Length);             // 2.4 写入FormData的结束边界符

         #endregion

         #region 步骤3：将表单域(内存流)写入 httpWebRequest 的请求流中，并发起请求
         httpWebRequest.ContentLength = memoryStream.Length;

         Stream requestStream = httpWebRequest.GetRequestStream();

         memoryStream.Position = ;
         byte[] tempBuffer = new byte[memoryStream.Length];
         memoryStream.Read(tempBuffer, , tempBuffer.Length);
         memoryStream.Close();

         requestStream.Write(tempBuffer, , tempBuffer.Length);        // 将内存流中的字节写入 httpWebRequest 的请求流中
         requestStream.Close();
         #endregion

         HttpWebResponse httpWebResponse = httpWebRequest.GetResponse() as HttpWebResponse; // 获取响应
         if (httpWebResponse != null)
         {
             //GetHeaders(ref httpResult, httpWebResponse);
             GetResponse(ref httpResult, httpWebResponse);
             httpWebResponse.Close();
         }
     }
     catch (WebException webException)
     {
         GetWebExceptionResponse(ref httpResult, webException);
     }
     catch (Exception ex)
     {
         GetExceptionResponse(ref httpResult, ex, method, HttpContentType.MULTIPART_FORM_DATA);
     }
     finally
     {
         if (httpWebRequest != null)
         {
             httpWebRequest.Abort();
         }
     }

     return httpResult;
 }

系列目录     【已更新最新开发文章，点击查看详细】