毕升Office的API调用前需要先获取API的授权签名。授权签名主要功能是验证用户身份,即确定当前的用户身份。
获取授权签名的方式为:业务方系统调用毕升Office授权签名API获取签名。
为确保安全,调用毕升office API(包括:调用API进行文件预览,编辑,调用毕升office服务端API)需要使用用户信息来进行签名授权,获取该用户的授权token。 该token参数在调用api时作为参数的一部分传入毕升office,毕升office系统将根据token值来验证用户信息。
如果你不需要此安全选项时,可以在控制台关闭授权签名。此后调用毕升office时将不再要求传入授权token。需要用户身份信息的API,根据API要求传入用户参数,具体参考相关API
默认情况下签名授权时开启的,如果需要关闭签名授权,可进入控制台关闭签名授权。
在调用毕升Office授权签名API前需要获取毕升Office系统的API密钥。该密钥是一个ak/sk密钥对。管理员用户可在系统管理页面/开发设置/API密钥页面中创建并获取。
创建成功后需要把密钥对下载至本地,且只能创建成功后即刻下载,请妥善保存。密钥对可以删除,删除之后该密钥对将从系统中移除。建议为不同的业务系统创建不同的API密钥。
下载的密钥对的格式如下:
其中access_key_id为ak,secret_access_key为sk,后续的使用过程中需要使用sk对时间字符串进行HMAC-MD5编码。
使用POST请求方式访问 http://bsd_host/apps/api/auth/apiSign地址可以获取API签名Token,在集成预览操作前获取一次即可。需要传递的参数如下:
{
"cert": {
"ak": "api_key_id",
"time": "2022-01-01 08:00:00",
"sign": "api_key_secret_sign_result"
},
"userId": "user001",
"syncUserUrl": ""
}
各字段的说明如下:
上述参数经过验证成功后将返回Token信息:
{
"status": true,
"token": "token_content"
}
例:当前API密钥对为ak:caa1lcgugtb3402r68e0,sk:caa1lcgugtb3402r68eg,time为2022-06-06 16:55:19。则使用sk对time的HMAC-MD5签名计算值为:4beabb34e066652728fd4b30e09b08e2,则得到的请求授权签名的参数如下:
{
"cert": {
"ak": "caa1lcgugtb3402r68e0",
"time": "2022-06-06 16:55:19",
"sign": "4beabb34e066652728fd4b30e09b08e2"
},
"userId": "xiedan"
}
接下来可以使用以上json信息作为参数请求毕升Office获取授权签名。例如使用以上参数请求得到的授权为:
{
"status":true,
"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJib2R5Ijp7InVzZXJJZCI6InhpZWRhbiIsInNpZCI6ImNhZXMxdG91Z3RiNjNhMXRrMTdnIiwiZmluZ2VycHJpbnQiOiIiLCJjVHlwZSI6IiIsImFrIjoiY2FhMWxjZ3VndGIzNDAycjY4ZTAifSwiZXhwIjoxNjU1MTk2OTE5LCJpYXQiOjE2NTQ1MDU3MTksIm5iZiI6MTY1NDUwNTUzOX0.QU67skGtrMZyDSncdH8bmzqYPG7Q12GPpBUX-UPU8xY4PlvYFjV1V4i8kiLBX7D2dihx90VGoLi99ZUX7ctrie_itu2FOREf4uYIPBVE9I3jneXDFU6n2-mZhdsmGT9D4vpHcW0yOdRj4X2T4742P_8dltL_1UL9c5G_HLqO1dt5mUjtOVlQh513BkjB6DNJOC9nhnnKhDfD5dDtSpnUKEOeGqqL8oQi8cbW1CB3REWkqhb81dWDTg-HuKA7wh5RtS70y0xs8WXdvRwrvKWtgV5Fe7Fndqq1XwKcctIKcsIMn15iW5kcI20iHPSTJuZEbZi-gdCl_ax6vuFPc1xvTA"
}
其中token为签名授权值。业务系统需要保存用户与签名授权的对应关系,以便在调用毕升服务时使用token作为参数,或在前端作为该用户的Cookie值保存。
以上流程可以用下图描述:
解析请求数据时,可能返回的错误信息如下:
进行账户同步处理时,可能返回的错误信息如下:
进行签名处理时,可能返回的错误信息如下:
授权签名是调用毕升Office API的凭证。在调用API时,需要授权签名作为参数。主要有如下使用场景:
毕升提供提供API key的HMAC-MD5签名测试仪供开发者进行测试。该测试方法可以用来测试开发者的HMAC-MD5签名算法是否正确。
调用url为:/apps/api/devTest/testApiKeyHMAC?ak=xxx&sk=xxx&time=xxx 请求方式为http get请求。
返回值如下:
{
status:true,
signed:"",
err:""
}
其中: signed为使用参数中的sk对参数中的time进行签名的结果。如果参数有错误,err将会返回错误原因。主要的错误原因有: