从发一条消息到接住每一次事件：飞书 Python SDK 上手全记录

从发一条消息到接住每一次事件飞书 Python SDK 上手全记录【免费下载链接】oapi-sdk-pythonLarksuite development interface SDK项目地址: https://gitcode.com/gh_mirrors/oa/oapi-sdk-python你是不是也干过这种事给飞书开放平台写一个机器人光把消息发出去这一步就得自己处理 token 怎么换、过期怎么续、响应怎么判错、事件回调的签名和加密怎么验。这些活儿每个应用都要写一遍烦不烦飞书 Python SDK包名lark-oapi干的就是这件事——它把开放平台 40 多个业务域的接口全部封装成client.xxx.v1.yyy()这样一层token 管理、加解密、请求签名、事件分发统统藏在底层。装好、配好 App ID 和 App Secret十行代码就能让你的机器人开口说话。上面这张图很能说明问题文档里一条/open-apis/contact/v3/users/:user_id的 HTTP 接口落到 SDK 里就是client.contact.v3.user.get()URL、token 类型、参数结构都不用你操心路径即代码。pip 一条命令发出第一条消息环境要求不高Python 3.8依赖requests、httpx、pycryptodome这些常规库pip install lark-oapi装完即用。装好之后先做两件事在飞书开放平台控制台建一个自建应用拿到 App ID 和 App Secret然后在应用后台给机器人开通获取与发送单聊、群聊消息的权限。接着就是最短路径——发一条文本消息到某个群import lark_oapi as lark from lark_oapi.api.im.v1 import * client lark.Client.builder() \ .app_id(cli_xxx).app_secret(your_secret).build() request CreateMessageRequest.builder() \ .receive_id_type(chat_id) \ .request_body(CreateMessageRequestBody.builder() \ .receive_id(oc_xxx) \ .msg_type(text) \ .content({text:hello world}) \ .build()) \ .build() response client.im.v1.message.create(request)跑通这一步之后值得多看一眼response这个对象response.success()判断业务是否成功response.code和response.msg是错误码和错误描述response.get_log_id()拿到的 log_id 是排查问题时和官方对接的关键凭证。养成不 success 就先看 log_id的习惯能省掉后面 80% 的抓瞎时间。40 个业务域按 client 属性一层层点过去SDK 把开放平台的服务按业务域拆成了独立的模块全部挂在client下面。你不需要背路径按域.版本.资源.动作四段式去点就行client.contact.v3.user/client.contact.v3.department通讯录管理。适合我要按手机号、邮箱换 open_id再拉部门成员这类基础数据操作是所有场景的起点。client.im.v1.message/client.im.v1.chat消息收发、群管理。机器人应用的主战场发消息、建群、拉人、改群名都在这里。client.approval.v4/client.task.v1审批与待办。适合做审批通过后自动建日程、派任务的流程自动化。client.calendar.v4/client.meeting_room.v1日历与会议。做日程提醒、会议室抢占类应用用。client.docx.v1/client.bitable.v1/client.sheets.v3云文档、多维表格、电子表格。适合把飞书表格当轻量数据库用的场景。client.drive.v1/client.drive.v2云盘文件上传下载发消息带附件之前先走它拿文件凭证。模块源码都在 lark_oapi/api/ 下每个域一个目录model/里是对应的请求/响应数据类想看某个接口的完整参数直接翻对应目录的.py文件比翻网页文档更快。samples/api/目录下按同样的目录结构放了大量现成示例比如samples/api/im/v1/就是消息接口全家桶照抄改参就行。接住事件HTTP 回调和长连接两条路能发消息只是单口相声机器人要能接住用户的话才叫对话。飞书事件订阅支持两种接入方式SDK 都包好了。方式一HTTP 回调。控制台配置请求地址后飞书会把事件 POST 到你的服务。SDK 提供EventDispatcherHandler负责验签、解密和分发你只管注册处理函数handler lark.EventDispatcherHandler.builder( lark.ENCRYPT_KEY, lark.VERIFICATION_TOKEN, lark.LogLevel.DEBUG) \ .register_p2_im_message_receive_v1(do_p2_im_message_receive_v1) \ .build()控制台里每个事件都对应一个register_xxx方法事件名和注册方法的映射关系在 lark_oapi/event/callback/ 的model/目录里能一一对上。下面这张图就是官方给的对应示意订阅了接收消息事件就注册register_p2_im_message_receive_v1。如果你的服务跑在 Flask 里可以直接用 lark_oapi/adapter/flask/ 的parse_req()/parse_resp()做请求适配samples/event/flask_sample.py是一个完整可跑的样例。方式二WebSocket 长连接本地开发神器。本地调试最怕公网回调地址不好搞SDK 的 lark_oapi/ws/ 模块提供长连接客户端ws.Client(app_id, app_secret, event_handlerhandler)启动后由 SDK 自己维持心跳、重连事件照样走上面注册好的 handlercli lark.ws.Client(lark.APP_ID, lark.APP_SECRET, event_handlerevent_handler, log_levellark.LogLevel.DEBUG) cli.start()samples/ws/sample.py就是长连接版完整示例。选型建议本地开发和单机小应用用长连接省事正式生产环境对并发和可用性有要求时HTTP 回调配合一个常驻服务更稳。把模块串起来三个真实业务场景单个接口会用了真正的价值在串联。给你三个常见的组合思路场景一机器人后按手机号找人并私聊。消息事件里只有 open_id要拿手机号得调client.contact.v3.user.get()反过来用户报一个手机号你要用client.contact.v3.user.batch_get_id()换出 open_id再走client.im.v1.message.create()私聊。三步串下来就是一个人肉路由。场景二审批通过自动通知。订阅审批状态变更事件p4系列的register_approval_instance回调事件里拿到instance_code查一下审批详情拿到申请人 open_id再发一条消息提醒。审批流 lark_oapi/api/approval/v4/ 和消息模块一搭就是典型的 OA 自动化。场景三非标准接口用 raw 请求。万一遇到某个新接口 SDK 还没生成对应方法不用等版本——lark.BaseRequest.builder()可以手动拼 URI、method、bodyclient.request(request)发出去token 注入依然自动完成。samples/api/raw.py里有上传文件、下载文件的完整写法multipart 场景照抄即可。踩坑指南这四个报错最常见99991663 / 99991668token 无效。大概率是 App ID 和 App Secret 配串了或者自建应用用了商店应用的 token 逻辑。SDK 会自动换取并缓存 tenant_access_token你唯一要做的是确认.app_id()和.app_secret()传的是同一套凭证。99992351 / 找不到聊天。发消息时receive_id对不上receive_id_type——oc_开头是 chat_idou_开头是 open_idon_开头是 union_id三者不能混。另一个高频原因你发的消息其实是机器人自己发的飞书不允许机器人回复机器人。事件回调 400 或 challenge 不通过。平台配置请求地址时会先发一个带challenge的 POST 验证你的服务必须原样返回这个值。用EventDispatcherHandler时它已经帮你处理了如果你是裸写路由检查是不是把 URL 写成了带路径的完整地址而不是平台要求的形式另外 ENCRYPT_KEY 如果开了加密验签解密也必须带上两个 Key 都取自控制台事件订阅页就是上面那张控制台截图里的位置。代码没报错但啥也没发生。事件没触发先查三处应用权限里对应的事件有没有开、控制台事件订阅里有没有添加、长连接客户端是不是真的start()成功打开 DEBUG 日志看。实在排查不动拿log_id去官方文档的 FAQ 页面对照或者在 SDK 反馈渠道贴出 log_id官方能直接查到网关侧的完整链路。再往前一步如果上面的 API 粒度还嫌细SDK 里有个更高层的 lark_oapi/channel/ 模块FeishuChannel一个类搞定收消息、去重、Markdown 转换、超长切分、媒体处理十几行代码就能跑一个带安全策略的 echo 机器人适合直接上生产的聊天机器人场景。再往外还有两个容易忽略的好东西lark.register_app()支持扫码一键注册应用连控制台建应用的步骤都能省掉client_assertion_provider无密钥模式则适合用外部签发服务管理凭证的企业级部署。现在就去终端敲下pip install lark-oapi把你手里那个机器人项目的第一个message.create跑起来吧。【免费下载链接】oapi-sdk-pythonLarksuite development interface SDK项目地址: https://gitcode.com/gh_mirrors/oa/oapi-sdk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考