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), 0, 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, "200");
            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 = -1)
{
    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 = -1)
{
    #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之间由 
--{boundary} 分割。
     *     (3) 表单域格式 ：Content-Disposition: form-data; name="{key}"


     *                   {value}

     *                   --{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 == 0)
    {
        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 == 0)
    {
        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 + "
");     // 边界符开始。【☆】右侧必须要有 
 。
    byte[] endBoundaryBytes = Encoding.UTF8.GetBytes("
--" + boundary + "--
"); // 边界符结束。【☆】两侧必须要有 --
 。
    byte[] newLineBytes = Encoding.UTF8.GetBytes("
"); //换一行
    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}"

" +
                                      "{1}
";

            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, 0, beginBoundaryBytes.Length); // 1.1 写入FormData项的开始边界符
                memoryStream.Write(formItemBytes, 0, formItemBytes.Length);           // 1.2 将键值对写入FormData项中
            }
        }
        #endregion

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

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

";

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

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

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

            i++;
        }

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

        #endregion

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

        Stream requestStream = httpWebRequest.GetRequestStream();

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

        requestStream.Write(tempBuffer, 0, 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;
}

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