WebAPI登记典型场景

1 业务背景

当金蝶云星瀚希望通过WebAPI登记与其他外部系统集成的时候，可使用集成服务云的WebAPI登记将外部系统暴露的API登记到集成云中以供调用。该文章主要针对登记过程中的各种常见问题进行讲解，具体登记过程详见文末参考资料。

2 典型场景

2.1 需要对URLEncode

参数编码通常用于确保传输的数据在HTTP传输过程中格式正确，比如使用Base64编码或者URL编码，以下图GET请求为例。

同样开启脚本模式以后，编辑脚本内容如下，直接使用MapToURLEncodeString函数将map转换为url参数字符串，并使用urlencode对其进行编码。

假如请求体是{'b':1,'a':2}，排序以后的新map是{'a':2,'b':1}，变成url参数格式以后再使用urlencode得到结果a=2&b=1。

注：生成新的url需要使用$$()，从而自动替换字符串中的#{}，比如$$("#{$website}#{$connection.web_app}/kapi")将自动将对应连接配置上的协议、ip、端口、web_app替换#{$website}和#{$connection.web_app}。

// 调用转换函数，格式化url参数
var urlParams = MapToURLEncodeString($urlParam);

var new_url=$$("#{$website}#{$connection.web_app}/kapi/v2/basedata/bd_customer/query?"+urlParams);

//head 	请求头变量
var head = {
    "Content-Type":"application/json",
    "accesstoken":$session.access_token
};
var dataStr = null;

//调用并返回结果body字符串
return HttpAccess(new_url, "GET", dataStr, "UTF-8", null, head, 0).result;

2.2 严格控制过期时间（过期的话重新获取token）

很多WebAPI都会通过过期时间来控制访问的安全性，比如一个API使用JWT（JSON Web Tokens）来控制访问。JWT中包含了过期时间（exp字段），如果当前时间超过了这个时间戳，那么请求将被拒绝。以下图API为例。

开启脚本模式以后，编辑脚本，使用$session.expire_time可以获取上次登录会话拿到的过期时间，对其进行判断以后可以使用Relogin()函数重新进行登录。

注：此处直接使用了Relogin()函数重新调用登录脚本获取新token，如果有对应刷新token的脚本也可直接走刷新逻辑。

var url = "https://open.feishu.cn:443/open-apis/contact/v3/users?department_id_type=department_id&user_id_type=user_id";

//如果过期时间小于当前时间的话，重新调用登录脚本获取tenant_access_token
if($session.expire_time<NOW){
  var head = {
    "Content-Type":"application/json",
    "Authorization":Relogin().tenant_access_token
};
}else{
  var head = {
    "Content-Type":"application/json",
    "Authorization":$session.tenant_access_token
};
}

//将请求体数据转换为JSON串
var dataStr = String.FormatJson($body);

//调用并返回结果body字符串
return HttpAccess(url, "POST", dataStr, "UTF-8", null, head, 0).result;

2.3 请求数据需要排序生成签名

在这种方式中，请求的参数按照一定的规则（如字典顺序）进行排序，并可能结合其他信息（如密钥）生成签名。这样做可以防止请求参数被篡改。以下图中的请求为例，假设我们需要根据原始请求参数排序以后转为字符串用MD5生成签名作为请求的参数。

开启脚本模式以后修改脚本如下，先使用sort函数对请求体的参数进行排序，然后生成新的Map，使用MapToURLEncodeString函数将map转换为url参数格式并进行URLEncode。将生成请求参数的字符串使用MD5加密，将得到的签名作为请求体的一个参数。

假如请求体是{'b':1,'a':2}，排序以后的新map是{'a':2,'b':1}，变成url参数格式以后再使用URLEncode得到结果a=2&b=1，最后使用MD5对该字符串进行加密以后的到签名b33b063ed6ac78b448048a5a3b1e1db1。

var url = $$("#{$website}