Senparc.Weixin.Work 企业微信 JSSDK agentConfig 实战:wx.agentConfig() 签名生成与审批流接口调用
Senparc.Weixin.Work 企业微信 JSSDK agentConfig 实战:wx.agentConfig() 签名生成与审批流接口调用
本文以 Senparc.Weixin.Work(企业微信模块)为背景,系统讲解企业微信网页 JSSDK 中 wx.agentConfig() 的完整接入流程:如何在服务端通过 SDK 的 JSSDKHelper 与 JsApiTicketContainer 生成 agentConfig 专属签名信息、如何在网页端完成 wx.agentConfig() 配置并通过 wx.invoke() 唤起审批流等特定接口。读完本文,你将掌握企业微信“应用级 JSSDK”区别于常规 JSSDK 的配置要点、多应用并存时的配置管理方式,以及签名票据的底层生成与缓存原理。
wx.agentConfig() 用于企业微信中某些特定的接口(如审批流接口、剪切板接口等)。与常规 JSSDK 不同,它要求签名基于应用的 jsapi_ticket(agent_config 类型票据)生成,而不是企业级 jsapi_ticket。在多数场景下,使用 agentConfig 之前需要先完成常规 JSSDK 的配置(参考 JSSDK(常规)),因此 agentConfig 是一个“增加项”,需要同时维护两套 JSSDK 配置。整个流程分为服务端获取签名信息和网页端配置 JSSDK 两部分。
理解 wx.agentConfig() 与常规 JSSDK 的关系
企业微信内置浏览器的 JSSDK 能力分为两级:
- 常规 JSSDK(
wx.config):面向企业全局开放的接口能力,如转发控制、调用摄像头、文件上传、关闭窗口、唤起扫码等,使用企业级 jsapi_ticket 生成签名; - agentConfig(
wx.agentConfig):面向特定应用的接口能力,如审批流接口(thirdPartyOpenPage)、剪切板接口等,使用应用级 jsapi_ticket 生成签名,签名时还需要提供corpid与agentid。
在编码层面,两者的服务端签名获取都复用同一个方法 JSSDKHelper.GetJsApiUiPackageAsync(),只是传入的参数不同;网页端则在常规 wx.config() 之外,额外增加一次 wx.agentConfig() 配置。仓库中的完整示例位于 JSSDKController.cs 与 Index.cshtml。
服务端:为 agentConfig 生成签名信息
第一步:在 appsettings.json 中配置多个企业微信应用
agentConfig 面向的是某个特定应用,因此服务端必须能够根据应用区分凭证信息。Senparc.Weixin SDK 通过 SenparcWeixinSetting.Items 节点支持同一 CorpId 下多个应用的注册。参考 appsettings.json:
"SenparcWeixinSetting": {
"IsDebug": true,
//企业微信
"WeixinCorpId": "#{WeixinCorpId}#",
"WeixinCorpAgentId": "#{WeixinCorpAgentId}#",
"WeixinCorpSecret": "#{WeixinCorpSecret}#",
"WeixinCorpToken": "#{WeixinCorpToken}#",
"WeixinCorpEncodingAESKey": "#{WeixinCorpEncodingAESKey}#",
"Items": {
//添加多个企业微信应用
"企业微信审批": {
"WeixinCorpId": "#{WeixinCorpId2}#",
"WeixinCorpAgentId": "#{WeixinCorpAgentId2}#",
"WeixinCorpSecret": "#{WeixinCorpSecret2}#",
"WeixinCorpToken": "#{WeixinCorpToken2}#",
"WeixinCorpEncodingAESKey": "#{WeixinCorpEncodingAESKey2}#"
},
"企业微信OAuth2.0": {
"WeixinCorpId": "#{WeixinCorpId3}#",
"WeixinCorpAgentId": "#{WeixinCorpAgentId3}#",
"WeixinCorpSecret": "#{WeixinCorpSecret3}#",
"WeixinCorpToken": "#{WeixinCorpToken3}#",
"WeixinCorpEncodingAESKey": "#{WeixinCorpEncodingAESKey3}#"
}
}
}
要点:
WeixinCorpId是企业微信账号独有的 corpId,同一企业内多个应用共享;WeixinCorpAgentId与WeixinCorpSecret对应每个应用的 agentId 与 secret;WeixinCorpToken与WeixinCorpEncodingAESKey对应消息接口回调的后台配置参数;Items下的每个 key(如“企业微信审批”)均可作为字典索引,通过Senparc.Weixin.Config.SenparcWeixinSetting["企业微信审批"]取出对应配置,并转换为ISenparcWeixinSettingForWork接口使用;- 这种“Items 多应用注册”的配置方式对所有其他模块同样通用(公众号、小程序、微信支付等)。
第二步:AgentConfig() 完整实现
在服务端 Action 中,需要同时生成常规 JSSDK 的 UI 信息包和 agentConfig 的 UI 信息包。以下代码来自仓库示例 JSSDKController.cs 的 AgentConfig() 方法:
public async Task<ActionResult> AgentConfig()
{
//此处演示同时支持多个应用的注册,请参考 appsettings.json 文件
var workSetting = Senparc.Weixin.Config.SenparcWeixinSetting["企业微信审批"] as ISenparcWeixinSettingForWork;
var url = "https://sdk.weixin.senparc.com/Work/Approval";
//获取 UI 信息包
/* 注意:
* 所有应用中,jsApiUiPackage 是必备的
*/
var jsApiTicket = await JsApiTicketContainer.GetTicketAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, false);
var jsApiUiPackage = await JSSDKHelper.GetJsApiUiPackageAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, url, jsApiTicket, false);
ViewData["jsApiUiPackage"] = jsApiUiPackage;
/* 注意:
* 1、这里需要使用 WeixinCorpAgentId,而不是 WeixinCorpId
* 2、agentJsApiUiPackage 是否需要提供,请参考官方文档,此处演示了最复杂的情况
*/
ViewData["thirdNo"] = DateTime.Now.Ticks + Guid.NewGuid().ToString("n");
ViewData["corpId"] = workSetting.WeixinCorpId;
ViewData["agentId"] = workSetting.WeixinCorpAgentId;
var agentConfigJsApiTicket = await JsApiTicketContainer.GetTicketAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, true);
var agentJsApiUiPackage = await JSSDKHelper.GetJsApiUiPackageAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, url, agentConfigJsApiTicket, true);
ViewData["agentJsApiUiPackage"] = agentJsApiUiPackage;
return View();
}
代码中有三个必须注意的关键点:
jsApiUiPackage是所有应用都必备的:即使只调用 agentConfig 专属接口,常规 JSSDK 的wx.config()依然要先行配置,因此两套 UI 信息包都要生成并传给前端;- agentConfig 的 ticket 获取与签名生成必须传
isAgentConfig: true:这是与常规 JSSDK 最核心的参数差异,决定了服务端拉取的是“应用 jsapi_ticket”而不是企业级 jsapi_ticket; agentid使用WeixinCorpAgentId:传给前端的agentId是应用 ID(如1000247),而不是 CorpId,网页端wx.agentConfig()校验时要求它必须与当前登录企业下的应用一致;thirdNo(第三方唯一标识)由DateTime.Now.Ticks + Guid.NewGuid().ToString("n")生成,用于审批流等接口的幂等/溯源参数。
第三步:底层原理——两套 jsapi_ticket 的获取与缓存
服务端差异的根源在于“普通 jsapi_ticket”与“应用 jsapi_ticket”是两种不同的票据,SDK 在三个层次上做了区分与封装:
1. CommonApi.GetTicket():不同的请求接口
在 CommonApi.cs 中,isAgentConfig 直接决定请求的 URL:
public static JsApiTicketResult GetTicket(string corpId, string corpSecret, bool isAgentConfig)
{
return ApiHandlerWapper.TryCommonApi(accessToken =>
{
//https://developer.work.weixin.qq.com/document/10029#%E8%8E%B7%E5%8F%96%E5%BA%94%E7%94%A8%E7%9A%84jsapi_ticket
var url = isAgentConfig
? $"{Config.ApiWorkHost}/cgi-bin/ticket/get?access_token={accessToken.AsUrlData()}&type=agent_config"
: $"{Config.ApiWorkHost}/cgi-bin/get_jsapi_ticket?access_token={accessToken.AsUrlData()}";
JsApiTicketResult result = CommonJsonSend.Send<JsApiTicketResult>(null, url, null, CommonJsonSendType.GET);
return result;
}, AccessTokenContainer.BuildingKey(corpId, corpSecret));
}
即:isAgentConfig = true 时请求 cgi-bin/ticket/get?type=agent_config(应用票据),false 时请求 cgi-bin/get_jsapi_ticket(企业票据)。
2. JsApiTicketContainer:按 isAgentConfig 区分缓存键并自动续期
JsApiTicketContainer.cs 是两种票据的缓存容器。其关键设计是:
RegisterAsync()在注册时会同时为普通与应用两种票据分别注册缓存项(遍历isAgentConfigArr = { true, false }),见 JsApiTicketContainer.cs;- 缓存键由
AccessTokenContainer.BuildingKey(corpId, corpSecret, isAgentConfig)生成,当isAgentConfig = true时键会带上@@AgentConfig标记(见 AccessTokenContainer.cs),从而将两种票据隔离缓存; GetTicketAsync(appId, appSecret, isAgentConfig, getNewTicket = false)在票据过期(或强制刷新)时自动重新向企业微信服务器获取,并使用分布式缓存锁避免并发重复请求,详见 JsApiTicketContainer.cs。
3. JSSDKHelper.GetJsApiUiPackageAsync():打包前端所需签名参数
JSSDKHelper.cs 的 GetJsApiUiPackageAsync() 负责把票据、随机串、时间戳组合并计算签名:
public static async Task<JsApiUiPackage> GetJsApiUiPackageAsync(string appId, string secret, string url, string jsApiTicket, bool isAgentConfig)
{
var nonceStr = GetNoncestr();
var timeStamp = GetTimestamp();
jsApiTicket ??= await JsApiTicketContainer.GetTicketAsync(appId, secret, isAgentConfig);
var sign = GetSignature(jsApiTicket, nonceStr, timeStamp, url);
JsApiUiPackage jsApiUiPackage = new(appId, timeStamp.ToString(), nonceStr, sign);
return jsApiUiPackage;
}
签名算法位于 JSSDKHelper.cs 的 GetSignature():
public static string GetSignature(string jsapi_ticket, string noncestr, long timestamp, string url)
{
StringBuilder sb = new StringBuilder();
sb.Append("jsapi_ticket=").Append(jsapi_ticket).Append("&")
.Append("noncestr=").Append(noncestr).Append("&")
.Append("timestamp=").Append(timestamp).Append("&")
.Append("url=").Append(url.IndexOf("#") >= 0 ? url.Substring(0, url.IndexOf("#")) : url);
return EncryptHelper.GetSha1(sb.ToString()).ToLower();
}
注意 url 会剔除 # 及其后面的部分,且必须是调用 JS 接口页面的完整 URL,与前端页面地址不一致会导致签名校验失败。最终返回的 JsApiUiPackage 包含 AppId、Timestamp、NonceStr、Signature 四个字段,正好对应前端 wx.config() 与 wx.agentConfig() 所需的参数。
说明:
GetJsApiUiPackageAsync()的jsApiTicket参数允许传null,此时方法内部会自动通过JsApiTicketContainer获取;示例代码中显式先获取再传入,是为了同时演示GetTicketAsync()的用法。
网页端:配置 wx.agentConfig() 并调用审批流接口
wx.agentConfig() 参数说明
wx.agentConfig() 的核心参数与 wx.config() 类似,但多了 corpid 与 agentid:
| 参数 | 必填 | 说明 |
|---|---|---|
corpid |
是 | 企业微信的 corpId,必须与当前登录的企业一致 |
agentid |
是 | 企业微信的应用 ID(如 1000247) |
timestamp |
是 | 生成签名的时间戳,来自服务端 agentJsApiUiPackage.Timestamp |
nonceStr |
是 | 生成签名的随机串,来自服务端 agentJsApiUiPackage.NonceStr |
signature |
是 | 签名,来自服务端 agentJsApiUiPackage.Signature |
jsApiList |
是 | 需要使用的接口名称列表,如 ['thirdPartyOpenPage'] |
完整前端调用代码
以下代码摘自仓库示例视图 Index.cshtml,在常规 wx.config() 配置完成后,执行特定 JsApi 方法之前补充 wx.agentConfig():
function invoke(){
wx.agentConfig({
corpid: '@ViewData["corpId"]', // 必填,企业微信的corpid,必须与当前登录的企业一致
agentid: '@ViewData["agentId"]', // 必填,企业微信的应用id (e.g. 1000247)
timestamp: @agentJsApiUiPackage.Timestamp, // 必填,生成签名的时间戳
nonceStr: '@agentJsApiUiPackage.NonceStr', // 必填,生成签名的随机串
signature: '@agentJsApiUiPackage.Signature',// 必填,签名,见附录-JS-SDK使用权限签名算法
jsApiList: ['thirdPartyOpenPage'], //必填,传入需要使用的接口名称
success: function(res) {
// 回调
wx.invoke('thirdPartyOpenPage', {
"oaType": "10001",// String
//"templateId": "C4NxepvGj51gbkeGXHQgYRArW96WrxRinNfyCxo7N",//SYS
"templateId":"247bcb886d0374a0a1f749c52794ba1a_622421053",// Open
"thirdNo": '@ViewData["thirdNo"]',// String
"extData": {
'fieldList': [{
'title': '审批类型',
'type': 'text',
'value': '文章审批',
},
{
'title': '预览',
'type': 'link',
'value': 'https://weixin.senparc.com',
}],
}
},
function(res) {
// 输出接口的回调信息
console.log(res);
alert('wx.invoke result:'+JSON.stringify(res));
});
},
fail: function(res) {
if(res.errMsg.indexOf('function not exist') > -1){
alert('版本过低请升级')
}
else{
alert('wx.invoke fail:'+JSON.stringify(res));
}
}
});
}
HTML 页面进行触发:<a href="javascript:void(0)" onclick="invoke()">点击唤起审批流程</a>。
几个实用细节:
wx.invoke('thirdPartyOpenPage', ...)是 agentConfig 成功后唤起审批流页面的调用方式;示例中oaType: "10001"表示打开类型,templateId区分“系统模板(SYS)”与“开放模板(Open)”两种审批模板,thirdNo对应服务端生成的第三方唯一标识,extData.fieldList用于传入审批单的自定义字段(文本、链接等);fail回调中通过res.errMsg.indexOf('function not exist')判断是否为客户端版本过低导致的接口不存在,从而给出“版本过低请升级”的提示,否则输出wx.invoke fail详情,便于排查签名或参数问题;success回调内的wx.invoke结果通过console.log(res)输出,alert中序列化展示。
完整接入流程回顾
一次完整的 agentConfig 接入链路为:
- 在 appsettings.json 的
Items节点为对应应用配置WeixinCorpId/WeixinCorpAgentId/WeixinCorpSecret等凭证; - 服务端在 JSSDKController.cs 的
AgentConfig()中:先取常规jsApiUiPackage(isAgentConfig = false),再取应用级agentJsApiUiPackage(isAgentConfig = true),并把corpId、agentId、thirdNo一并放入ViewData; - 网页端在 Index.cshtml 中先完成常规
wx.config(),再调用wx.agentConfig()完成应用级授权,最后在success回调中wx.invoke()唤起审批流等特定接口; - 票据生命周期由
JsApiTicketContainer自动托管:两种票据(普通 / agent_config)以isAgentConfig区分缓存键,过期自动通过CommonApi.GetTicket()重新拉取,开发者无需关心刷新细节。
总结
wx.agentConfig() 的接入本质上是“第二套 JSSDK 配置”:服务端复用 JSSDKHelper.GetJsApiUiPackageAsync() 但以 isAgentConfig = true 拉取应用级 jsapi_ticket 并生成签名,前端在常规 wx.config() 之外追加一次带 corpid/agentid 的 wx.agentConfig(),之后即可通过 wx.invoke() 调用审批流、剪切板等应用级接口。本文对应的可运行完整示例位于 Samples/Work,核心源码与配置参考如下:
- 服务端 Action:JSSDKController.cs
- 前端视图:Index.cshtml
- 多应用配置:appsettings.json
- 签名与 UI 信息包生成:JSSDKHelper.cs
- 票据容器与自动续期:JsApiTicketContainer.cs
- 票据拉取接口区分:CommonApi.cs
- UI 信息包实体:JsApiUiPackage.cs
若你的业务只需企业级 JSSDK 能力(转发、扫码、上传等),可先参考 JSSDK(常规) 的接入方式;需要应用级能力时再在此基础上叠加本文的 agentConfig 配置即可。