|
ps：本文中部分代码为截图，如有需要复制，可从wiki获取：高效处理资源集成难题
在进行多系统集成的时候，是不是经常会被各种集成问题给难到，集成很多细节点没有注意导致集成失败，引发了一系列的疑问：
- 为什么openresource集成请求参数传递失败？
- 为什么令牌token令牌解析失败？
- 为什么令牌token登录之后参数传递失败
- ......
下面我们就从基础出发，深入探究集成的秘密。
一、openresource集成问题
注意本节介绍的内容只是单独使用openresource时的注意事项，默认均是已完成单点登录的集成。
1、选择正确的传参字符串json
在资源集成的时候，openresource请求的paramsInfo、paramsInfoBase64两个参数是用来传递参数，传递的参数信息需要一个json格式的字符串。在不同的资源里其传递的字符串格式是不一样的，所以需要根据不同的资源选择正确的参数json串，选择正确的传参字符串参数传递的问题可以解决很多参数传递失败的问题。
http://localhost:18080/smartbi/vision/openresource.jsp?resid=I402881e5019608c408c4fb7801960e2ec9b42d3d¶msInfo=
各资源参数选择如下
电子表格、旧即席查询、旧透视分析
单参数： [{"name":"发货区域", "value":"华北","displayValue":"华北"}]
多参数： [{"name":"发货区域", "value":"华北","displayValue":"华北"},{"name":"订单年份", "value":"2020","displayValue":"2020"} ]
多选参数：[{"name":"订单年份", "value":"2020,2021","displayValue":"2020,2021"}]
仪表盘、新即席查询、新透视分析
单参数： {"订单年份":{"values":["2020"]}}
多参数： {"订单年份":{"values":["2020"]}, {"订单月份":{"values":["2020-01"]} }
多选参数：{"订单年份":{"values":"2020,2021" }} , {"订单年份":{"values":["2020","2021"]}} 或 [{"name":"订单年份", "value":["2020","2021"],"displayValue":["2020","2021"] }]
注意：仪表盘除去以上格式之外也支持使用电子表格的参数传递方式
多选参数注意事项
- 由于电子表格里参数是通过英文逗号进行分割多个参数，所以在多个参数传递的时候只能写成"value":"2020,2021" ，若业务数据中不规范有逗号，则会解析为两个参数，由于电子表格的架构实际目前无法解决该问题。
- 仪表盘上的参数逻辑不同于电子表格，不仅可以写成"values":"2020,2021"和电子表格的逻辑一致，还额外提供了数组的写法"values":["2020","2021"]。此时需要注意，如果使用数组的写法，数组中的每一项表示一个参数，如写为"values":["2020,2021"]则表示传递的参数是2020,2021的整体，而不是拆分成两个参数，可解决业务数据中有英文逗号的问题。
2、url转码
在选择正确的参数之后，拼接得到最终访问资源的请求，具体可以参考如下示例。那么如下链接如果直接访问会有哪些问题呢？
http://localhost:18080/smartbi/vision/openresource.jsp?resid=I402881e5019608c408c4fb7801960e2ec9b42d3d¶msInfo==[{"name":"发货区域", "value":"华北","displayValue":"华北"}]
HTTP状态 400 - 错误的请求
在参数的链接中我们可以发现其存在中文数据，同时也存在特殊字符，访问时就很可能会出现如下Tomcat报错"HTTP状态 400 - 错误的请求"的报错，在报错的描述信息中可以看到原本paramsInfo后面加的参数变成了一堆编码，其错误描述中大致的意思是请求信息中有无效的字符导致的。
出现这个问题是因为tomcat高版本严格按照RFC 3986规范解析地址。该规范只允许包含a-zA-Z 0-9 - _ . ~ 以及所有保留字符 ! * ’ ( ) ; : @ & = + $ , / ? # [ ] 通常情况下参数中使用的保留字符并不会识别为参数的内容，而是识别为请求相关的内容。
所以当请求中有除去上述的特殊字符或中文的时候会被Tomcat的限制，会识别不到请求所以抛出400的错误状态码。那实际遇到这种问题的时候又该如何解决呢？
方案一：使用 encodeURIComponent 函数进行url转码
url转码是浏览器请求时面对不合法的请求时进行转化的重要手段，实现的原理是将需要转码的字符，按指定编码方式（默认使用UTF-8编码）转化为字节流，然后每个字节按16进制表示，最后添加%组成一个percent编码，最终就会变成%+16进制+16进制的格式
例如：你好
- UTF-8字节流打印为：-28 -67 -96 -27 -91 -67
- 对应的16进制表示为：E4 BD A0 E5 A5 BD
- URLEncode编译后为：%E4%BD%A0%E5%A5%BD
此时转码之后的字符就可以被浏览器识别，所以只需要将paramsInfo后面的参数内容全部进行url转码之后拼接到请求中就可以被Tomcat识别。如下这里我们直接在浏览器控制台中使用encodeURIComponent，得到的结果拼接成完整的url请求具体如下。此时就可以正常访问并且传参成功，在实际开发场景中只需要将拼接之后参数json进行字符串格式化之后再拼接到请求中即可完成参数传递。
http://localhost:18080/smartbi/vision/openresource.jsp?resid=I402881e5019608c408c4fb7801960e2ec9b42d3d¶msInfo=%5B%7B%22name%22%3A%22%E5%8F%91%E8%B4%A7%E5%8C%BA%E5%9F%9F%22%2C%22value%22%3A%22%E5%8D%8E%E5%8C%97%22%2C%22displayValue%22%3A%22%E5%8D%8E%E5%8C%97%22%7D%5D
方案二：修改tomcat的server.xml配置文件
在Tomcat/conf/server.xml文件中，可以在请求端口的配置中添加relaxedPathChars="|{}[],%"和relaxedQueryChars="|{}[],%" 两个参数同样也可解决该问题，特殊情况下还需要多添加一个URIEncoding="UTF-8" 的参数，避免因为字符集导致的转码异常。
注意：若为window一键安装部署Tomcat，默认情况下这些参数是已经添加过的。
测试html文件： open.html (4.69 K)（测试资源仅提供测试验证以及参考，实际的集成时请以实际场景为准）
下载后双击打开html文件，输入需要集成资源的openresource地址之后，选择不加密，然后在下方添加需要传递的参数以及参数值，最后点击拼接url之后即可得到完整的集成链接，访问拼接的地址可验证参数是否正常传递成功。
3、base64加密
在实际生产的过程中使用openresource.jsp集成资源的时候，除去会遇到Tomcat无法识别字符的问题之外，还可能或有参数过多请求头过长请求被拦截、请求中大量的特殊字符被网络安全策略拦截等各式各样的场景，那是否还有其他办法规避掉这些问题？
base64加密流程
（1）配置好需要加密的参数，这里以发回区域参数为例，如：[{"name":"发货区域", "value":"华北","displayValue":"华北"}]
（2）用加密算法进行加密，加密要点如下：
- 使用base64加密是需要以UTF-8的字符集来进行加密
- 建议使用sun.misc.BASE64Encoder类来加密处理，也可以使用js代码来处理，但是不作为首要推荐，因为加密不一致时解密可能会异常。
- 加密完成后需要对加密后的字符串进行转码
（3）使用encodeURLComponent对加密后的字符串进行转码。
- 加密之后的base64串是可能包含除字母之后的一些特殊字符的，所以一定需要进行url转码，否则Smartbi在加解密的时候就会报错，前端页面显示500，如下图：
 
base64参考示例
java代码实现参考：
// 对格式化的json字符串sourceString使用UTF-8字符集进行加密
String targetTempString = new sun.misc.BASE64Encoder().encode(sourceString.getBytes(StandardCharsets.UTF_8));
// 对加密后的字符串进行url转码
String targetString = java.net.URLEncoder.encode(targetTempString);
js代码实现参考：
// 1、对参数进行字符串转换，json格式化
let jsonString = JSON.stringify(params);
// 2、对字符串的数据转为二进制
let utf8Bytes = new TextEncoder().encode(jsonString);
// 3、用二进制的数据转为utf-8之后进行base64编码
let base64Encoded = btoa(String.fromCharCode(...utf8Bytes));
// 4、对base64编码进行url转义
return encodeURIComponent(base64Encoded)
最终访问地址拼接示例如下：
http://localhost:18080/smartbi/vision/openresource.jsp?resid=I402881e5019608c408c4fb7801960e2ec9b42d3d¶msInfoBase64=W3sibmFtZSI6IuS6p%2BWTgeWQjeensCIsICJ2YWx1ZSI6IuWNjuWMlyIsImRpc3BsYXlWYWx1ZSI6IuWNjuWMlyJ9XQ%3D%3D
测试html文件：open.html (4.69 K)（测试资源仅提供测试验证以及参考，实际的集成时请以实际场景为准）
下载后双击打开html文件，输入需要集成资源的openresource地址之后，选择不加密，然后在下方添加需要传递的参数以及参数值，最后点击拼接url之后即可得到完整的集成链接，访问拼接的地址可验证参数是否正常传递成功。
4、post请求提交
前面介绍的集成方式都是通过get请求来进行集成的，集成的时候有发现存在各种浏览器的限制问题，有没有什么方式能直接绕开这些限制的传参方式呢？
在Smartbi中支持通过form表单的形式来提交post请求来进行集成，使用post请求来进行集成时基本上可以规避很多get请求时会出现的问题，实现的方式可以参考下面的简单示例。
post集成示例拆解
示例总共有四个部分组成，下面我们来逐步拆解
（1）设置提供表单的响应区域
在实际的集成场景中，比较常见的就是点击了某些类似资源树上的节点之后再在页面上展示集成资源的结果，这里我们需要使用
（2）form表单部分
在form标签中需要设置的参数如下：
- method="post"：请求方式设置为post。
- action="http://localhost:18080/smartbi/vision/openresource.jsp"：提交post请求的地址
- target=""：见前一小节
这样设置完成之后当form表单提交的时候就可以用post请求的方式给openresource请求，并按照指定的方式展示响应资源。
（3）参数部分
在form标签内，需要使用input标签来写需要传递的参数内容，这里的input标签必须要需要设置的内容如下：
- name="resid"：标签中的name属性是提交post请求参数的参数名
- value="I402881e5019608c408c4fb7801960e2ec9b42d3d"：标签里的value属性是提交post请求参数的参数值
在一个input标签中name和value需要同时存在，否则传参异常。多个openresource请求的参数需要用多个input标签
使用post请求来给打开资源传参的时候，除去可以在input标签中设置name属性为paramsInfo然后value中直接等于传参的json之外，还支持简易版本的传参方式，两种传参方式具体如下。注意两种传参方式选择其一即可。
方式一：使用paramsInfo传参
实际post请求时的参数负载
方式二：使用param.参数名传参
- param.参数名：参数的真实值
- paramDisplay.参数名：参数的显示值
- 打开自助仪表盘资源时，参数名对应为筛选器组件的标题
实际post请求时的参数负载
（4）表单提交
这里form表单提交是通过使用js代码来进行控制，这种提交方式相对于在form表单中添加submit类型的button标签的提交按钮更灵活，毕竟在实际的集成场景很难控制让用户点击提交表单的按钮，另外就是使用js代码提交时候还能在提交前去设置form表单的一些属性。
// 获取form标签
var submitForm = document.getElementById("submitForm");
// 在设置的iframe中打开
submitForm.target = "myFrame"
submitForm.submit();
参考示例页面：postHtml.html (1.51 K)（测试资源仅提供测试验证以及参考，实际的集成时请以实际场景为准）
使用时请用文本工具打开并修改里面的服务器地址信息以及集成的参数资源。
调优部分
由于form表单本身需要在html页面上创建form标签以及传参的input标签，在实际基础场景中集成参数不会是一直固定的，所以在实际集成时，可以在html上预留好ifarme标签位置之后，使用js代码根据实际需要来动态创建标签，实际更符合业务需求。
参考示例页面：post.html (2.1 K)（测试资源仅提供测试验证以及参考，实际的集成时请以实际场景为准）
二、令牌token单点登录
在Smartbi中使用令牌token进行单点登录的时候，往往会因为在加密时某一个步骤操作不当导致出现各式各样的问题，可能遇到的问题如下：
问题1：令牌token单点登录：解析令牌失败
问题2：其他提示信息，如令牌超时、用户不存在等
 
问题3：报错自定义的提示信息
如果在系统选项中设置了自定义的异常提示，前台的提示信息就不是很明显，此时可以打开系统监控然后监控日志，就能看到如下日志，可确认是上述问题中的那一个
 
在使用令牌token的时候要如何避免这些问题，在生成和使用令牌的时候又要注意哪些问题呢？下面我们就用一个代码示例来确认来讲解：
（1）加密参数部分
加密参数主要由四部分组成
- 秘钥：设置的秘钥要与Smartbi的config界面配置的秘钥一致，不一致则可能会出现问题1“解析令牌失败”的问题。另外令牌一般设置8个字符，否则AES算法时会加密异常。
- 时间戳：时间戳需要获取当前时间，确保第三方系统时间和Smartbi服务器的时间差距不大，否则可能会出现问题2“令牌超时”的问题。
- 用户名：用户名需要传入Smartbi上用户的用户名，同时确保Smartbi上存在对应用户，否则会出现问题2“用户不存在”的问题，需要做好用户同步
- 密码：密码是可选传入，若config上配置了需要传入密码，则一定需要传入。
（2）进行加密
加密部分主要有主要有两种算法DES加密和AES-GCM加密
- DES加密：CryptoUtil.encrypt(AlgorithmType.DES, loginInfo, 密钥)。
- AES-GCM加密：smartbi.crypto.CryptoUtil.encrypt(loginInfo, 密钥) 或 CryptoUtil.encrypt(AlgorithmType.AES_GCM, loginInfo, secretKey)
注意秘钥长度，如果秘钥不是8个字符的，使用AES-GCM加密加密会报错如下：The key length must be 16 bytes
加密注意事项：
- V11版本不同的加密算法得到的结果是不一样的，令牌的前缀一般会表示当前使用的是什么样的加密算法，T1_表示AES算法、T0_表示为DES算法。而V10版本的加密算法是没有前缀的，需要特别注意。
- V11版本使用的加密jar包和V10版本使用的jar包不一致，加密出来的结果也完全不一致。
下面使用相同用户、密码、时间戳、令牌，算法不同来加密之后得到的结果参考如下：
// V10版本加密之后的令牌
54f296bd4649b0d44628a5c32faee32b8dcc1603e65f5926bcff5ecd042f5176ebefa28274987245be277798ca3175c6ac93f1e0ae92bd16841e7713b31959e6edf967ea6f13b4bc
// V11版本DES算法加密之后的令牌
T0_VPKWvUZJsNRGKKXDL67jK43MFgPmX1kmvP9ezQQvUXbr76KCdJhyRb4nd5jKMXXGrJPx4K6SvRaEHncTsxlZ5u35Z+pvE7S8
// V11版本AES算法加密之后的令牌
T1_DNEJke1569+HbJtUBb9a4m9l1ZtI4UR4CGUfwn+mMsuuw9PkNKoHAchSpoXDxc0CsFgVwVMlibe9uOa+QliqOrNxg05qz7ZzDlHNLYCsvi6kmliCNBPio2MstouYIw==
（3）令牌转码
拿到令牌之后我们可以看到如下令牌他是存在特殊字符的，又因为令牌单点一般都是通过get请求来提交令牌参数，此时就可能会出现上一章节的相同问题：2、url转码。此时就需要对令牌进行url转码，如果是Java系统可以使用 java.net.URLEncoder.encode(token, "UTF-8")进行转码，js代码则可以使用encodeURIComponent函数来进行转码。如果说不转码的情况下拼接地址访问之后，同样会出现问题1“解析令牌失败”的问题。
（4）拼接登录链接
拼接的单点地址需要使用loginByToken，然后smartbiToken参数用来指定
token："http://localhost:8080/smartbi/vision/loginByToken?smartbiToken=" + encodedToken;
（5）拼接登录后的跳转请求
登录完成之后，需要使用targetPath参数来指定跳转之后需要拼接的地址，这个地址在拼接到最终请求之前同样需要进行url转码，否则在openresource的请求里，当设置集成报表的参数时，会将集成的参数当成是loginByTokenq请求的参数，导致openresource请求传参失败，具体可以参考如下图中的请求参数信息。
 
最终拼接访问的请求如下：
http://localhost:18080/smartbi/vision/loginByToken?smartbiToken=T1_DNEJke1569%2BHbJtUBb9a4m9l1ZtI4UR4CGUfwn%2BmMsuuw9PkNKoHAchSpoXDxc0CsFgVwVMlibe9uOa%2BQliqOrNxg05qz7ZzDlHNLYCsvi6kmliCNBPio2MstouYIw%3D%3D&targetPath=openresource.jsp%3Fresid%3D2472fece6b5e9162c5ecf31425ac3b6c%26paramsInfo%3D%255B%257B%2522name%2522%253A%2522%25E5%258F%2591%25E8%25B4%25A7%25E5%258C%25BA%25E5%259F%259F%2522%252C%2522value%2522%253A%2522%25E5%258D%258E%25E5%258C%2597%2522%252C%2522displayValue%2522%253A%2522%25E5%258D%258E%25E5%258C%2597%2522%257D%255D
如果大家在类似场景里遇到过其他棘手的问题，欢迎在评论区分享你的‘踩坑’经历和解决妙招 ~~ | 
