企业微信开发(一) 认证、主调、回调

11 篇文章 0 订阅

回调模式

在回调模式下,企业不仅可以主动调用企业号接口,还可以接收成员的消息或事件。接收的信息使用XML数据格式、UTF8编码,并以AES方式加密

企业号的每个应用都有自己的回调模式开关。在管理端开启并设置好相关参数后,此应用的回调模式才生效。

针对加解密的处理,微信提供了各种语言的库,企业可以在附录中下载。


开启应用的回调模式

当你开启应用的回调模式时,企业号会要求你填写应用的URL、Token、EncodingAESKey三个参数。

URL是企业应用接收企业号推送请求的访问协议和地址,支持http或https协议。

Token可由企业任意填写,用于生成签名。

EncodingAESKey用于消息体的加密,是AES密钥的Base64编码。

验证URL、Token以及加密的详细处理请参考后续'接收消息时的加解密处理'的章节。


Hdms.png

验证URL有效性

当你提交以上信息时,企业号将发送GET请求到填写的URL上,GET请求携带四个参数,企业在获取时需要做urldecode处理,否则会验证不成功。

参数描述是否必带
msg_signature微信加密签名,msg_signature结合了企业填写的token、请求中的timestamp、nonce参数、加密的消息体
timestamp时间戳
nonce随机数
echostr加密的随机字符串,以msg_encrypt格式提供。需要解密并返回echostr明文,解密后有random、msg_len、msg、$CorpID四个字段,其中msg即为echostr明文首次校验时必带

企业通过参数msg_signature对请求进行校验,如果确认此次GET请求来自企业号,那么企业应用对echostr参数解密并原样返回echostr明文(不能加引号,不能带bom头),则接入验证生效,回调模式才能开启。

后续回调企业时都会在请求URL中带上以上参数(echostr除外),校验方式与首次验证URL一致。


使用回调模式

企业号在回调企业URL时,会对消息体本身做AES加密,以XML格式POST到企业应用的URL上;企业在被动响应时,也需要对数据加密,以XML格式返回给微信。企业的回复支持文本、图片、语音、视频、图文等格式

微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。如果在调试中,发现成员无法收到响应的消息,可以检查是否消息处理超时。

当接收成功后,http头部返回200表示接收ok,其他错误码一律当做失败并发起重试

关于重试的消息排重,有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime排重。

假如企业无法保证在五秒内处理并回复,可以直接回复空串,企业号不会对此作任何处理,并且不会发起重试。这种情况下,可以使用发消息接口进行异步回复。

假设企业回调URL为http://api.3dept.com

  • 请求说明:

http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&timestamp=13500001234&nonce=123412323

  • 回调数据格式:
<xml> 
   <ToUserName><![CDATA[toUser]]</ToUserName>
   <AgentID><![CDATA[toAgentID]]</AgentID>
   <Encrypt><![CDATA[msg_encrypt]]</Encrypt>
</xml>

1.msg_encrypt为经过加密的密文
2.AgentID为接收的应用id,可在应用的设置页面获取
3.ToUserName为企业号的CorpID

企业需要对msg_signature进行校验,并解密msg_encrypt,得出msg的原文。

  • 被动响应给微信的数据格式:
<xml>
   <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
   <MsgSignature><![CDATA[msg_signature]]></MsgSignature>
   <TimeStamp>timestamp</TimeStamp>
   <Nonce><![CDATA[nonce]]></Nonce>
</xml>

1.msg_encrypt为经过加密的密文,算法参见附录
2.MsgSignature为签名,算法参见附录
3.TimeStamp为时间戳,Nonce为随机数,由企业自行生成


接收消息时的加解密处理

企业可以直接使用微信提供的库进行加解密的处理,目前提供的有c++/python/php/java/c#等语言版本。代码提供了解密、加密、验证URL三个接口,企业可根据自身需要下载 (参见附录的加解密库下载)。以下为库函数的使用说明(以c++为例),更详细的加解密方案请参考(附录)。

1、解密函数

int DecryptMsg(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sPostData, string &sMsg);
  • 参数说明
参数必须说明
sMsgSignature从回调URL中获取的msg_signature参数
sTimeStamp从回调URL中获取的timestamp参数
sNonce从回调URL中获取的nonce参数
sPostData从回调URL中获取的整个post数据
sMsg用于返回解密后的msg,以xml组织
  • 返回说明

请参阅附录加解密部分。

2、加密函数

int EncryptMsg(const string &sReplyMsg, const string &sTimeStamp, const string &sNonce, string &sEncryptMsg);
  • 参数说明
参数必须说明
sReplyMsg返回的消息体原文
sTimeStamp时间戳,调用方生成
sNonce随机数,调用方生成
sEncryptMsg用于返回的密文,以xml组织
  • 返回说明

请参阅附录加解密部分。

3、验证URL函数

int VerifyURL(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sEchoStr, string &sReplyEchoStr);
  • 参数说明
参数必须说明
sMsgSignature从回调URL中获取的msg_signature参数
sTimeStamp从回调URL中获取的timestamp参数
sNonce从回调URL中获取的nonce参数
sEchoStr从回调URL中获取的echostr参数。注意,此参数必须是urldecode后的值
sReplyEchoStr解密后的echostr,用于回包。注意,必须原样返回,不要做加引号或其它处理
  • 返回说明

请参阅附录加解密部分。


获取微信服务器的ip段

  • 请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/getcallbackip?access_token=ACCESS_TOKEN

  • 参数说明
参数必须说明
access_token调用接口凭证
  • 返回结果
{
   "ip_list": ["101.226.103.*", "101.226.62.*"]
}

主动调用

主动调用是最基本的连接模式,当你的应用调用企业号时,需使用Https协议、Json数据格式、UTF8编码,访问域名为https://qyapi.weixin.qq.com,数据包不需要加密

在每次主动调用企业号接口时需要带上AccessToken参数。AccessToken参数由CorpIDSecret换取。

CorpID是企业号的标识,每个企业号拥有一个唯一的CorpID;Secret是管理组凭证密钥。

系统管理员可通过管理端的权限管理功能创建管理组,分配管理组对应用、通讯录的访问权限。完成后,管理组即可获得唯一的secret。系统管理员可通过权限管理查看所有管理组的secret,其他管理员可通过设置中的开发者凭据查看。

当企业应用调用企业号接口时,企业号后台为根据此次访问的AccessToken,校验访问的合法性以及所对应的管理组的管理权限以返回相应的结果。

注:你应该审慎配置管理组的权限,够用即好,权限过大会增加误操作可能性及信息安全隐患。

获取AccessToken

AccessToken是企业号的全局唯一票据,调用接口时需携带AccessToken。

AccessToken需要用CorpIDSecret来换取,不同的Secret会返回不同的AccessToken。正常情况下AccessToken有效期为7200秒,有效期内重复获取返回相同结果;有效期内有接口交互(包括获取AccessToken的接口),会自动续期

  • 请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=id&corpsecret=secrect

  • 参数说明
参数必须说明
corpid企业Id
corpsecret管理组的凭证密钥
  • 权限说明

每个secret代表了对应用、通讯录的不同权限;不同的管理组拥有不同的secret。

  • 返回说明

a)正确的Json返回结果:

{
   "access_token": "accesstoken000001",
   "expires_in": 7200
}
参数说明
access_token获取到的凭证
expires_in凭证的有效时间(秒)

b)错误的Json返回示例:

{
   "errcode": 43003,
   "errmsg": "require https"
}


主动调用的频率限制

当你获取到AccessToken时,你的应用就可以成功调用企业号后台所提供的各种接口以管理或访问企业号后台的资源或给企业号成员发消息。

为了防止企业应用的程序错误而引发企业号服务器负载异常,默认情况下,每个企业号调用接口都有一定的频率限制,当超过此限制时,调用对应接口会收到相应错误码。

以下是当前默认的频率限制,企业号后台可能会根据运营情况调整此阈值:

  • 基础频率

每企业调用单个cgi/api不可超过1000次/分,30000次/小时

每ip调用单个cgi/api不可超过2000次/分,60000次/小时

第三方应用提供商由于需要同时服务于多个企业,ip频率限制如下:每ip调用单个cgi/api不可超过20000次/分,600000次/小时

  • 发消息频率

每企业不可超过帐号上限数*30人次/天

  • 创建帐号频率

每企业创建帐号数不可超过帐号上限数*3/月

  • 创建应用频率

每企业最大应用数限制为30个,创建应用次数不可超过30*3/月



  • 0
    点赞
  • 3
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
基于Binary Wang,一种Java开源库,可以很方便地实现企业微信开发应用的回调事件。企业微信开发应用是指在企业微信平台上开发的应用,可以通过回调事件与企业微信平台进行交互。回调事件是指当用户在企业微信上进行某些操作时,企业微信平台会主动向开发者的应用发送相应的事件通知。以下是具体的实现步骤: 首先,我们需要使用Binary Wang库中的相关类和方法来处理回调事件。可以通过在应用的代码中引入相应的依赖来获取该库。然后,创建一个类来处理回调事件,并在该类中定义处理每个具体事件的方法。 接下来,我们需要在企业微信开发者后台进行相应的配置。具体来说,需要设置应用的回调URL,即当有事件发生时,企业微信平台会向该URL发送回调通知。在回调URL中,需要处理企业微信发来的请求,解析其中的参数,并调用之前创建的类中相应的方法来处理事件。 在处理每个具体事件的方法中,开发者可以根据自身需求来编写相应的业务逻辑。例如,当有新用户加入企业微信时,可以发送欢迎消息;当有用户发送文本消息时,可以进行关键词过滤等等。 此外,为了保证回调事件的安全性,企业微信开发者后台还提供了签名验证的功能。在处理回调URL的代码中,开发者需要对企业微信发送的请求进行签名验证,以确保请求的合法性。 总的来说,基于Binary Wang可以很方便地实现企业微信开发应用的回调事件。通过处理回调事件,开发者可以针对用户在企业微信上的操作做出相应的响应,实现更丰富、个性化的企业微信应用。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值