Senparc.Weixin.Work 企业微信 JSSDK agentConfig 实战:wx.agentConfig() 签名生成与审批流接口调用

原创2026-09-24 15:09:241,896 阅读
文章标签:后端即时通讯API设计

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();
}

代码中有三个必须注意的关键点:

  1. jsApiUiPackage 是所有应用都必备的:即使只调用 agentConfig 专属接口,常规 JSSDK 的 wx.config() 依然要先行配置,因此两套 UI 信息包都要生成并传给前端;
  2. agentConfig 的 ticket 获取与签名生成必须传 isAgentConfig: true:这是与常规 JSSDK 最核心的参数差异,决定了服务端拉取的是“应用 jsapi_ticket”而不是企业级 jsapi_ticket;
  3. agentid 使用 WeixinCorpAgentId:传给前端的 agentId 是应用 ID(如 1000247),而不是 CorpId,网页端 wx.agentConfig() 校验时要求它必须与当前登录企业下的应用一致;
  4. 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 接入链路为:

  1. 在 appsettings.json 的 Items 节点为对应应用配置 WeixinCorpId / WeixinCorpAgentId / WeixinCorpSecret 等凭证;
  2. 服务端在 JSSDKController.cs 的 AgentConfig() 中:先取常规 jsApiUiPackage(isAgentConfig = false),再取应用级 agentJsApiUiPackage(isAgentConfig = true),并把 corpId、agentId、thirdNo 一并放入 ViewData;
  3. 网页端在 Index.cshtml 中先完成常规 wx.config(),再调用 wx.agentConfig() 完成应用级授权,最后在 success 回调中 wx.invoke() 唤起审批流等特定接口;
  4. 票据生命周期由 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,核心源码与配置参考如下:

若你的业务只需企业级 JSSDK 能力(转发、扫码、上传等),可先参考 JSSDK(常规) 的接入方式;需要应用级能力时再在此基础上叠加本文的 agentConfig 配置即可。

登录后查看全文
WeiXinMPSDK