Lark最大的优点,就是有类似于Telegram的「机器人」机制。机器人可以推送通知,可以通过按钮、指令,处理一些简单的东西,比如预约会议室,确认服务上线,等等。
到目前为止,我自己已经使用Python写了三个机器人了(OCR小助手、定时自动换头像和标注队列助手),经历了内部同事自己封装的SDK,也用过开放平台官方的SDK,踩了不少坑,也在内部群里看到很多人踩同样的坑。单独水成好几篇文章没太大意思,那就写成一个小集合,顺带做个基于Flask的脚手架代码,放Github上。为了尽可能多地演示功能,可能代码不是特别精简。
任务
示例代码中,将实现下面几个基本功能:
- 对话消息
- 用户给机器人发送一个数字N,机器人返回随机N段文字
- 用户给机器人发送两个数字N和M,机器人在M秒种后随机返回N段文字
- 用户给机器人发送一个数字N,并有一个参数
--card
,机器人使用卡片返回随机N段文字 - 用户给机器人发送两个数字N和M,并有一个参数
--card
,机器人在M秒种后使用卡片返回随机N段文字
- 指令消息(
/
开头的消息)- 在「对话消息」前面加入
/get
指令。其余参数和作用
- 在「对话消息」前面加入
- 卡片消息
- 用户点击卡片上的「更换一批」,机器人更新卡片上的N段文字
- 用户点击卡片上的「M秒钟后更换一批」,机器人更新卡片上的N段文字
开放平台配置
申请权限
需要申请的权限不多
配置回调
把服务起起来,得到IP+端口。
代码编写
Git在这里:https://github.com/jinyu121/lark_bot_demo
异步处理文字消息
这里要先说一下整个处理流程,也就是说,从「用户给机器人发消息」,到「用户看到机器人返回的消息」,中间都发生了什么。
- 用户给机器人发消息
- 消息到达Lark/飞书服务器,服务器将消息转发/投递到你的应用(叫做「事件回调」)
- 你的应用处理消息,并给Lark/飞书服务器返回一个200消息,表示「消息已收到」
- 在「你的应用处理消息」的过程中,给用户发了一条或多条消息
好了,这就算完了。注意重点,「你的应用给飞书/Lark服务器返回一个200消息」表示「这个消息我收到了」,这事儿就算完了,Lark/飞书服务器并没有要求你必须「再发一个消息告诉用户什么什么东西」。
那么,用户的感觉是「我给机器人发送消息,机器人响应了我」,这个是怎么做到的呢?注意看「你的应用处理消息」,这个「处理」可能包含各种东西,例如打Log,例如查数据库,再例如,给用户发消息。对的,「给用户发消息」只是「处理消息」过程中的一个可选项,是机器人「主动」做的,并且可以做许多次。
有了上面的理解,我们就可以写最最基本的代码了。最基本的代码可以见SDK的官方Demo。这个Demo写的是「收到消息回调,显示消息内容」,不涉及「回复消息」。
必须在1秒内返回结果:将实际处理放到线程里
Lark/飞书有个比较奇怪的设定:用户给机器人发消息,机器人应用收到消息后,必须在1秒内返回一个200响应,表示「我收到消息了」。如果你的处理比较简单,例如只是查个数据库,更改个状态啥的,那么1秒钟内绝对能处理得完。但如果你的处理比较重、比较耗时,例如文件下载、图片过识别模型、处理视频,那么1秒钟是不够用的。这个时候,如果你超时了,没有在1秒种内返回个200确认,那么Lark/飞书服务器就会认为「消息投递失败」,于是会在5秒、5分钟、1小时、6小时后分别再尝试投递一次消息。但是呢,都说了处理消息很耗时,同一个消息处理,这次20秒才能处理完,下次不可能1秒就处理完呀,于是当服务器再次投递消息的时候,你依旧会超时。这样不仅你的应用会重复处理,如果处理过程中有「给用户发消息」的操作的话,用户也会多次收到消息,体验不好(想象下晚上1点收到消息的抓狂)。
这个时候,我们可以这样做:收到Lark/飞书服务器转发来的消息后,新开一个线程用于慢慢处理消息,同时主线程直接返回200,让Lark/飞书服务器认为「投递消息成功」,避免消息再次投递。而且因为Lark/飞书服务器需要的只是一个200的状态确认,不强制要求于用户交互(不强制要求要「回应」用户消息),所以我们可以将「确认收到消息」和「实际处理」分开。
这里一切都看起来「理所当然」,但是很快就会遇到一个问题:在新开的处理线程里面无法获取到 current app
,导致一大堆事儿干不了。这里我们使用一个叫 flask-thread
的包来替代Python原生的thread。这个包是对原生thread包的很薄的一层封装,主要干的事儿就是把flask的 app_stack
给传到了线程里,这样线程里面就能用 current_app
了。
消息滤重:Redis
上面说了,「如果在1秒内没返回结果,那么会Lark/飞书服务器会延迟一会儿再重复投递消息」。在将消息处理放到线程里后,99.999%的情况下,都可以在1秒内返回个200确认出来,同时线程里面也将该处理的东西都处理了,该通知的用户也都发了消息。但是,你自己这里万事OK了,Lark/飞书服务器也是会抽风的啊,比如网络出现了什么岔子,导致Lark/飞书服务器没收到这个200确认,咋办?总不能老老实实再处理一遍,再通知一遍用户?
所以Lark/飞书在转发消息的时候,都会带上消息id,我们可以利用消息id进行消息去重。在处理完成后,我们可以把消息id记录到数据库中,再来消息的时候就先检查下数据库,如果消息id在数据库中,那么说明这个是重复消息,不用处理,只管回个200敷衍确认下就好了;如果不在数据库里,那么该干啥就干啥。
这里推荐使用「带过期时间」的数据库(例如,redis)来做这个事儿。一个是因为这种记录性质的东西本身不是啥重要内容,永久存储的话划不来;另一个是,Lark/飞书人家也说了,超过6个小时后就不会再投递了,也就是说这个id过了6个小时后就完全没用了,永久存储的话没意义。所以,使用redis,设置个最多12小时的过期时间,就能满足要求了。
子线程需要带上请求环境
写起来都挺简单的。但是写不久就会遇到一个问题:这个线程只有「应用」环境,没有「请求」环境。所以如果只是纯Python的操作,例如打打Log,整理整理数据库啥的还好说,但是如果想使用url_for
等东西,就会报错,或者结果不符合预期,比如报「没有BasePath」啥啥的,不能生成相对URL,只能生成绝对URL,这个对灵活部署十分不友好。
所以解决方法也很简单,带上请求环境,或者模拟个请求环境,不就好了么。Flask里面提供了这样的函数(copy_current_request_context
),直接用就是了,但是我自己在使用的时候,就「这句话应该写在哪儿」纠结了好几个早上,最终发现应该写在生成线程的地方。
from flask import copy_current_request_context
from flaskthreads import AppContextThread
AppContextThread(target=copy_current_request_context(some_function)).start())
同步处理卡片消息
这里也先说一下,从用户和卡片交互,到用户收到「与卡片交互完成」,中间发生了啥:
- 用户点击卡片上的可交互元素(例如,按钮,下拉选框等),将交互的「值」传给Lark/飞书服务器
- Lark/飞书服务器将交互的「值」转发给你的应用
- 你的应用进行处理,并给Lark/飞书服务器返回交互结果(例如卡片内容更新)
- Lark/飞书服务器将交互结果返回给用户,改变用户端可以看到的卡片
可以看出来,这里的处理方式和上面处理消息的方式不同:上面是「随便回个200,确认下收到消息就完事儿了」,这里是「一定要返回个处理结果」。并且,由于是交互,所以成功就是成功,失败就是失败(失败后用户可以自己重试),Lark/飞书服务器不会自动重新投递消息。
最基本的代码见SDK官方Demo。这个Demo写的是「收到消息卡片回调,更新卡片内容」。
参数传递
如果只是「展示消息卡片」,那么不需要传递啥东西。
如果需要「交互」,那么就需要考虑一下了。如果用户点击卡片上的按钮后,回传给自己服务的永远都是纯纯的「用户点击了按钮」,那么我完全不知道它按了啥。所以用户点击卡片上的东西之后,肯定是需要回传一些特殊的东西,我才能对不同卡片进行不同处理。
在文档里面,我们可以看到,如果是按钮,那么会有 valu
e这个东西,也就是说,点击按钮后,value
将被回传给我们的应用。如果是 SelectMen
u和 Overflo
w,它的值有两部分,一部分是固定的 value
,另一部分是每个选项的 value
,在回传的时候,会回传固定部分的value和你选择的东西。
OK,那么我们应该如何进行路由呢?最简单的办法是,把路由信息写在value里面,然后我们的程序解析value,得到路由终端。比如,我使用 catrgory
来标记「使用哪个类进行处理」,使用 action
来标记「使用类中的哪个方法进行处理」。至于其他固定参数,我固定写在 data
里。
必须在3秒内返回结果:异步更新卡片
由于是同步更新,所以「等待时间」不能太长,否则体验不好。Lark/飞书要求的是在3秒内处理完,并返回结果。一般来说这个时间是凑合够用的:卡片一般用在「确认」场景,做的重活、耗时的活儿比较少。
如果是这样的话,那么我们就可以开始写代码了。
当然,如果你能预料到你的卡片干的活比较重、比较耗时,不保证在3秒之内能完成处理,那么也可以仿照上面处理消息的套路,先快速返回一个「200消息确认+不更新卡片」,然后单独开一个线程处理消息,处理完成后,使用「异步更新卡片」更新交互的卡片。
最后是个吐槽
嗯,Lark/飞书的开放平台和SDK确实不咋好用,Lark/飞书本身也抛弃了之前那么漂亮的设计,改成了现在这个比较奇怪的模样,连Logo也变成了异形扳手。另外Lark目前越做越大,越来越「大而全」,我不知道是不是个好事儿。功能越来越多的话,就像在逛杂货铺,真的是啥功能都有,但是「能一击解决我的痛点」的功能,越来越少了。但总之,要比国内某个蓝色软件和绿色软件好用得多得多。
然后是,Lark/飞书Python SDK的Demo的「重复感」太强了,想找啥东西都有种「从三叶草丛(重复的东西)里面找四叶草(不重复的东西)」的感觉。两个Demo,里面只有两三行不一样,作者的想法是「随便打开一个文件,东西都是完整的」,但我并不认为这是个好想法。
然后,有几个词我一直不理解为啥要这样叫,比如「免登」,比如特色功能「Reaction」是不是翻译成「回应」会更好一点(目前是「表情回复」,我觉得怪怪的)。
最后,Go版本的SDK,可以试试这个。
发表回复