C#开发BIMFACE系列15 服务端API之获取模型的View token

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

在《C#开发BIMFACE系列3 服务端API之获取应用访问凭证AccessToken》中详细介绍了应用程序访问API的令牌凭证。我们知道 Access token 代表自身应用的身份，使用应用的 appkey, secret，通过调用/oauth2/token接口获取。BIMFACE所有的接口调用都需要传递 Access token 。

本篇主要介绍 ViewToken。

View token

代表对单个模型/集成模型/模型对比的访问权限，使用 access token，通过调用/view/token或其他相关接口获得。

使用 Access token，可以对自己应用内的文件发起文件上传，下载，删除，模型转换，模型集成，模型对比等操作， 同时也能访问所有 BIMFACE 的数据接口获取转换后的模型BIM信息；而 View token 只代表对单个模型/集成模型/模型对比的临时的访问凭证， 只能访问对应模型的数据接口，通过使用应用的 Access token 调用下面的接口可以获得。 通常情况下，View token 可以直接传入前端 JSSDK 用来加载/浏览模型。

View token的使用方法是在调用对应的数据接口的时候，添加一个查询参数（Query parameter）：

view_token={your_view_token}

只有在文件转换或模型集成任务成功以后，才能获取View token。

请求地址：GET https://api.bimface.com/view/token

说明：通过fileId, integrateId, compareId 获取View token, 然后把View token传入前端JavaScript组件提供的接口中，即可加载和浏览文件所包含的三维模型或二维图纸。

参数：application/octet-stream

请求 path(示例)：https://api.bimface.com/view/token

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

HTTP响应示例(200)：

{
    "code": "success",
    "message": null,
    "data": "389c28de59ee62e66a7d87ec12692a76"
}

失败时返回：

{
    "code": "authentication.failed",
    "message": "Token was not recognized."
}

失败时返回的错误码：

C#实现方法：

 /// <summary>
 ///  获取模型的 ViewToken
 /// </summary>
 /// <param name="accessToken">令牌</param>
 /// <param name="modelType">模型类型</param>
 /// <param name="objectId">文件转换ID(fileId)、模型对比ID(compareId)、集成模型ID(integrateId)的值，三者中的一个</param>
 /// <returns></returns>
 protected ViewTokenResponse GetViewToken(string accessToken, ModelType modelType, long objectId)
 {
     //GET https://api.bimface.com/view/token
     string url = string.Format(BimfaceConstants.API_HOST + "/view/token?{0}={1}", modelType.ToString(), objectId);
     BimFaceHttpHeaders headers = new BimFaceHttpHeaders();
     headers.AddOAuth2Header(accessToken);

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

         return response;
     }
     catch (Exception ex)
     {
         throw new Exception("[获取ViewToken] 发生异常！", ex);
     }
 }

其中调用到的 httpManager.Get() 方法，请参考《C# HTTP系列》

其中 ModelType 枚举，是为了区分不同模型的种类

 /// <summary>
 ///  模型类型枚举
 /// </summary>
 public enum ModelType
 {
     /// <summary>
     /// 文件转换ID
     /// </summary>
     fileId,

     /// <summary>
     /// 模型对比ID
     /// </summary>
     compareId,

     /// <summary>
     /// 集成模型ID
     /// </summary>
     integrateId
 }

为了使调用更加的方便，扩展了3个更细致的方法

 /// <summary>
 ///  获取单个模型的 ViewToken
 /// </summary>
 /// <param name="accessToken">令牌</param>
 /// <param name="fileId">文件转换ID</param>
 /// <returns></returns>
 public ViewTokenResponse GetViewTokenByFileId(string accessToken, long fileId)
 {
     return GetViewToken(accessToken, ModelType.fileId, fileId);
 }

 /// <summary>
 ///  获取模型集成的 ViewToken
 /// </summary>
 /// <param name="accessToken">令牌</param>
 /// <param name="integrateId">集成模型ID</param>
 /// <returns></returns>
 public ViewTokenResponse GetViewTokenByIntegrateId(string accessToken, long integrateId)
 {
     return GetViewToken(accessToken, ModelType.integrateId, integrateId);
 }

 /// <summary>
 ///  获取模型比对的 ViewToken
 /// </summary>
 /// <param name="accessToken">令牌</param>
 /// <param name="compareId">模型比对ID</param>
 /// <returns></returns>
 public ViewTokenResponse GetViewTokenByCompareId(string accessToken, long compareId)
 {
     return GetViewToken(accessToken, ModelType.compareId, compareId);
 }

测试

在BIMFACE的控制台中可以看到我们上传的文件列表，共计2个文件。模型状态均为转换成功。

【获取ViewToken】、【公开链接】按钮只有在模型转换成功之后才启用。

调用上面封装的方法来测试是否能获取到viewToken，以第一个文件“rac_advanced_sample_project-三维视图 - From Parking Area.dwg” 为例

在BIMFACE控制台中查看该文件的ViewToken

可以看到两者的结果是一致的。

测试程序如下：

 // 获取 ViewToken【文件转换ID】
 protected void btnGetViewTokenByFileId_Click(object sender, EventArgs e)
 {
     BasicApi api = new BasicApi();
     ViewTokenResponse response = api.GetViewTokenByFileId(txtAccessToken.Text, txtFileId.Text.ToLong());

     txtResult.Text = response.Code
                    + Environment.NewLine
                    + response.Message
                    + Environment.NewLine
                    + response.Data.ToString2();
 }

返回的结果对应的实体类如下：

 /// <summary>
 ///  获取 ViewToken 的请求返回结果类
 /// </summary>
 [Serializable]
 public class ViewTokenResponse : GeneralResponse<string>
 {

 }

继承的基类如下：

 /// <summary>
 ///  请求 BIMFACE 服务端 API的响应结果统一的返回类
 /// </summary>
 [Serializable]
 public class GeneralResponse<T> //where T : class, new()
 {
     #region 属性

     /// <summary>
     ///  请求返回代码，success 或者 xxxx.failed。
     /// </summary>
     [JsonProperty("code")]
     public virtual string Code { get; set; }

     /// <summary>
     ///  失败的错误原因。
     ///  如果 Code 为 success 则 Message 为空。
     ///  如果 Code 为 xxxx.failed 则 Message 为具体的失败信息。
     /// </summary>
     [JsonProperty("message")]
     public virtual string Message { get; set; }

     /// <summary>
     ///  执行成功后的返回结果
     /// </summary>
     [JsonProperty("data")]
     public virtual T Data { get; set; }

     #endregion

     #region 构造函数
     public GeneralResponse()
     {
     }

     public GeneralResponse(T data)
     {
         this.Data = data;
     }

     #endregion

     #region 方法
     public override string ToString()
     {
         if (Data != null)
         {
             return string.Format("GeneralResponse [code={0}, message={1}, data={2}]", Code, Message, Data);
         }
         else
         {
             return string.Format("GeneralResponse [code={0}, message={1}, data={2}]", Code, Message, "");
         }
     }

     #endregion
 }

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