C#开发BIMFACE系列15 服务端API之获取模型的View token
- 2019 年 10 月 4 日
- 筆記
在《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#实现方法：
1 /// <summary> 2 /// 获取模型的 ViewToken 3 /// </summary> 4 /// <param name="accessToken">令牌</param> 5 /// <param name="modelType">模型类型</param> 6 /// <param name="objectId">文件转换ID(fileId)、模型对比ID(compareId)、集成模型ID(integrateId)的值，三者中的一个</param> 7 /// <returns></returns> 8 protected ViewTokenResponse GetViewToken(string accessToken, ModelType modelType, long objectId) 9 { 10 //GET https://api.bimface.com/view/token 11 string url = string.Format(BimfaceConstants.API_HOST + "/view/token?{0}={1}", modelType.ToString(), objectId); 12 BimFaceHttpHeaders headers = new BimFaceHttpHeaders(); 13 headers.AddOAuth2Header(accessToken); 14 15 try 16 { 17 ViewTokenResponse response; 18 HttpManager httpManager = new HttpManager(headers); 19 HttpResult httpResult = httpManager.Get(url); 20 if (httpResult.Status == HttpResult.STATUS_SUCCESS) 21 { 22 response = httpResult.Text.DeserializeJsonToObject<ViewTokenResponse>(); 23 } 24 else 25 { 26 response = new ViewTokenResponse 27 { 28 Message = httpResult.RefText 29 }; 30 } 31 32 return response; 33 } 34 catch (Exception ex) 35 { 36 throw new Exception("[获取ViewToken] 发生异常！", ex); 37 } 38 }
其中调用到的 httpManager.Get() 方法，请参考《C# HTTP系列》
其中 ModelType 枚举，是为了区分不同模型的种类
1 /// <summary> 2 /// 模型类型枚举 3 /// </summary> 4 public enum ModelType 5 { 6 /// <summary> 7 /// 文件转换ID 8 /// </summary> 9 fileId, 10 11 /// <summary> 12 /// 模型对比ID 13 /// </summary> 14 compareId, 15 16 /// <summary> 17 /// 集成模型ID 18 /// </summary> 19 integrateId 20 }
为了使调用更加的方便，扩展了3个更细致的方法
1 /// <summary> 2 /// 获取单个模型的 ViewToken 3 /// </summary> 4 /// <param name="accessToken">令牌</param> 5 /// <param name="fileId">文件转换ID</param> 6 /// <returns></returns> 7 public ViewTokenResponse GetViewTokenByFileId(string accessToken, long fileId) 8 { 9 return GetViewToken(accessToken, ModelType.fileId, fileId); 10 }
1 /// <summary> 2 /// 获取模型集成的 ViewToken 3 /// </summary> 4 /// <param name="accessToken">令牌</param> 5 /// <param name="integrateId">集成模型ID</param> 6 /// <returns></returns> 7 public ViewTokenResponse GetViewTokenByIntegrateId(string accessToken, long integrateId) 8 { 9 return GetViewToken(accessToken, ModelType.integrateId, integrateId); 10 }
1 /// <summary> 2 /// 获取模型比对的 ViewToken 3 /// </summary> 4 /// <param name="accessToken">令牌</param> 5 /// <param name="compareId">模型比对ID</param> 6 /// <returns></returns> 7 public ViewTokenResponse GetViewTokenByCompareId(string accessToken, long compareId) 8 { 9 return GetViewToken(accessToken, ModelType.compareId, compareId); 10 }
测试
在BIMFACE的控制台中可以看到我们上传的文件列表，共计2个文件。模型状态均为转换成功。
【获取ViewToken】、【公开链接】按钮只有在模型转换成功之后才启用。
调用上面封装的方法来测试是否能获取到viewToken，以第一个文件“rac_advanced_sample_project-三维视图 – From Parking Area.dwg” 为例
在BIMFACE控制台中查看该文件的ViewToken
可以看到两者的结果是一致的。
测试程序如下：
1 // 获取 ViewToken【文件转换ID】 2 protected void btnGetViewTokenByFileId_Click(object sender, EventArgs e) 3 { 4 BasicApi api = new BasicApi(); 5 ViewTokenResponse response = api.GetViewTokenByFileId(txtAccessToken.Text, txtFileId.Text.ToLong()); 6 7 txtResult.Text = response.Code 8 + Environment.NewLine 9 + response.Message 10 + Environment.NewLine 11 + response.Data.ToString2(); 12 }
返回的结果对应的实体类如下：
1 /// <summary> 2 /// 获取 ViewToken 的请求返回结果类 3 /// </summary> 4 [Serializable] 5 public class ViewTokenResponse : GeneralResponse<string> 6 { 7 8 }
继承的基类如下：
1 /// <summary> 2 /// 请求 BIMFACE 服务端 API的响应结果统一的返回类 3 /// </summary> 4 [Serializable] 5 public class GeneralResponse<T> //where T : class, new() 6 { 7 #region 属性 8 9 /// <summary> 10 /// 请求返回代码，success 或者 xxxx.failed。 11 /// </summary> 12 [JsonProperty("code")] 13 public virtual string Code { get; set; } 14 15 /// <summary> 16 /// 失败的错误原因。 17 /// 如果 Code 为 success 则 Message 为空。 18 /// 如果 Code 为 xxxx.failed 则 Message 为具体的失败信息。 19 /// </summary> 20 [JsonProperty("message")] 21 public virtual string Message { get; set; } 22 23 /// <summary> 24 /// 执行成功后的返回结果 25 /// </summary> 26 [JsonProperty("data")] 27 public virtual T Data { get; set; } 28 29 #endregion 30 31 #region 构造函数 32 public GeneralResponse() 33 { 34 } 35 36 public GeneralResponse(T data) 37 { 38 this.Data = data; 39 } 40 41 #endregion 42 43 #region 方法 44 public override string ToString() 45 { 46 if (Data != null) 47 { 48 return string.Format("GeneralResponse [code={0}, message={1}, data={2}]", Code, Message, Data); 49 } 50 else 51 { 52 return string.Format("GeneralResponse [code={0}, message={1}, data={2}]", Code, Message, ""); 53 } 54 } 55 56 #endregion 57 }
