别再只会发文本了！用Python给飞书机器人发送带按钮和图片的卡片消息（附完整代码）
用Python打造飞书机器人交互式卡片消息：从基础到实战
在企业协作场景中，飞书机器人早已超越简单的文本通知，成为自动化流程的重要枢纽。想象一下：当服务器出现异常时，收到的不是晦涩难懂的日志文本，而是附带诊断按钮和可视化图表的精美卡片；当日报生成时，呈现的不是枯燥数据表格，而是带有趋势图和详情链接的交互式报告。这正是飞书消息卡片能带来的体验升级。
1. 消息卡片设计基础与核心元素
飞书消息卡片本质上是一个结构化的JSON对象，通过精心设计的布局和丰富的交互元素，将信息以更直观的方式呈现。与普通文本消息相比，卡片消息支持Markdown格式化文本、图片、按钮、分割线、备注等十多种元素，并能通过交互按钮触发后续动作。
核心组件解析：
{ "msg_type": "interactive", "card": { "header": { "title": { "content": "服务器报警通知", "tag": "plain_text" }, "template": "red" }, "elements": [ { "tag": "markdown", "content": "**CPU使用率**已达95%，超过阈值90%" }, { "tag": "action", "actions": [ { "tag": "button", "text": { "content": "查看详情", "tag": "plain_text" }, "url": "https://monitor.example.com", "type": "primary" } ] } ] } }表：消息卡片主要元素功能对照
| 元素类型 | 功能描述 | 常用属性 |
|---|---|---|
header | 卡片标题区 | title(标题内容)、template(颜色模板) |
markdown | 富文本内容 | content(支持加粗、斜体等语法) |
img | 嵌入图片 | img_key(图片资源标识) |
action | 交互按钮组 | actions(包含多个按钮定义) |
div | 内容分隔区 | text(纯文本内容) |
note | 备注信息 | elements(可包含文本和图片) |
实际开发中，飞书提供了消息卡片搭建工具，通过可视化界面拖拽组件即可生成对应的JSON结构，极大降低了开发门槛。对于Python开发者而言，需要掌握的是如何将这些结构通过代码动态生成并发送。
2. Python集成开发全流程
要实现自动化发送卡片消息，我们需要完成从环境准备到消息发送的完整链路。以下是经过生产验证的最佳实践方案：
2.1 环境配置与依赖安装
首先确保Python环境版本≥3.7，并安装必要依赖：
pip install requests pyyaml python-dotenv推荐使用.env文件管理敏感配置：
# .env FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/your_webhook_token FEISHU_SECRET=your_signature_secret # 如果启用了签名校验2.2 安全策略实现
飞书机器人提供三种安全机制，建议至少启用其中一种：
- IP白名单：仅允许指定IP范围的请求
- 关键词校验：消息必须包含预设关键词
- 签名校验（推荐）：基于时间戳和密钥的HMAC加密
签名校验的Python实现：
import hashlib import base64 import hmac import time def generate_signature(secret): timestamp = str(int(time.time())) string_to_sign = f"{timestamp}\n{secret}" hmac_code = hmac.new( string_to_sign.encode("utf-8"), digestmod=hashlib.sha256 ).digest() return { "timestamp": timestamp, "sign": base64.b64encode(hmac_code).decode("utf-8") }2.3 消息发送核心类封装
以下是一个经过优化的消息发送工具类：
import json import os from dotenv import load_dotenv import requests load_dotenv() class FeishuCardSender: def __init__(self): self.webhook_url = os.getenv("FEISHU_WEBHOOK") self.secret = os.getenv("FEISHU_SECRET") def _add_security_headers(self, headers=None): if not self.secret: return headers or {} signature = generate_signature(self.secret) security_headers = { "X-Lark-Request-Timestamp": signature["timestamp"], "X-Lark-Request-Nonce": str(int(time.time() * 1000)), "X-Lark-Signature": signature["sign"] } return {**(headers or {}), **security_headers} def send_card(self, card_content): payload = { "msg_type": "interactive", "card": card_content } headers = { "Content-Type": "application/json", **self._add_security_headers() } response = requests.post( self.webhook_url, data=json.dumps(payload), headers=headers ) return response.json()3. 高级卡片设计实战
3.1 动态数据报表卡片
将数据库查询结果转化为可视化卡片：
def build_report_card(data): # 假设data包含CPU、内存等指标 markdown_content = f""" **服务器状态报告** 🖥️ **CPU使用率**: {data['cpu']}% 🧠 **内存占用**: {data['memory']}GB 📊 **磁盘空间**: {data['disk']}% **最近1小时趋势** 👉 峰值: {data['peak']}% at {data['peak_time']} 👉 均值: {data['average']}% """ return { "header": { "title": {"content": "系统健康报告", "tag": "plain_text"}, "template": "wathet" # 青蓝色 }, "elements": [ { "tag": "markdown", "content": markdown_content }, { "tag": "hr" # 水平分割线 }, { "tag": "action", "actions": [ { "tag": "button", "text": {"content": "查看详情", "tag": "plain_text"}, "url": data['dashboard_url'], "type": "default" }, { "tag": "button", "text": {"content": "静默报警", "tag": "plain_text"}, "url": data['mute_url'], "type": "danger" } ] } ] }3.2 图片与多按钮组合
上传图片到飞书后获取img_key，然后嵌入卡片：
{ "config": {"wide_screen_mode": true}, "elements": [ { "tag": "img", "img_key": "img_v3_025c41a", "alt": {"content": "销售趋势图", "tag": "plain_text"} }, { "tag": "action", "actions": [ { "tag": "button", "text": {"content": "下载报告", "tag": "plain_text"}, "url": "https://example.com/report.pdf", "type": "primary" }, { "tag": "button", "text": {"content": "调整参数", "tag": "plain_text"}, "url": "https://example.com/params", "type": "default" } ] } ] }3.3 多模块信息整合
通过note元素添加辅助信息：
def build_multi_module_card(): return { "header": { "title": {"content": "项目日报", "tag": "plain_text"}, "template": "purple" }, "elements": [ { "tag": "div", "text": { "tag": "lark_md", "content": "**今日进展**\n✅ 完成用户模块开发\n⏳ 正在进行支付接口联调" } }, { "tag": "note", "elements": [ { "tag": "plain_text", "content": "明日计划：完成测试用例编写" } ] } ] }4. 企业级应用场景解析
4.1 CI/CD构建通知
将传统的构建日志转换为交互式卡片：
def build_ci_card(build_info): status_emoji = "✅" if build_info["success"] else "❌" status_color = "green" if build_info["success"] else "red" return { "header": { "title": { "content": f"构建 #{build_info['number']} {status_emoji}", "tag": "plain_text" }, "template": status_color }, "elements": [ { "tag": "markdown", "content": f""" **项目**: {build_info['project']} **分支**: `{build_info['branch']}` **耗时**: {build_info['duration']}秒 **提交者**: {build_info['committer']} **变更**: {build_info['changes']} files """ }, { "tag": "action", "actions": [ { "tag": "button", "text": {"content": "查看日志", "tag": "plain_text"}, "url": build_info["log_url"], "type": "primary" }, { "tag": "button", "text": {"content": "重新构建", "tag": "plain_text"}, "url": build_info["rebuild_url"], "type": "default" } ] } ] }4.2 审批流程集成
将审批请求转化为可操作的卡片：
{ "config": {"wide_screen_mode": true}, "elements": [ { "tag": "markdown", "content": "**费用报销申请**\n\n申请人: 张三\n金额: ¥1,280.00\n事由: 客户招待费用" }, { "tag": "action", "actions": [ { "tag": "button", "text": {"content": "同意", "tag": "plain_text"}, "type": "primary", "value": {"action": "approve", "id": "12345"} }, { "tag": "button", "text": {"content": "拒绝", "tag": "plain_text"}, "type": "danger", "value": {"action": "reject", "id": "12345"} }, { "tag": "button", "text": {"content": "转交", "tag": "plain_text"}, "type": "default", "value": {"action": "transfer", "id": "12345"} } ] } ] }4.3 数据监控告警
实时监控数据的可视化呈现：
def build_alert_card(metric): trend_arrow = "↑" if metric["trend"] > 0 else "↓" return { "header": { "title": {"content": f"{metric['name']}告警", "tag": "plain_text"}, "template": "red" }, "elements": [ { "tag": "column_set", "columns": [ { "tag": "column", "width": "weighted", "weight": 1, "elements": [ { "tag": "markdown", "content": f"**当前值**: {metric['value']}{metric['unit']}" } ] }, { "tag": "column", "width": "weighted", "weight": 1, "elements": [ { "tag": "markdown", "content": f"**变化趋势**: {trend_arrow} {abs(metric['trend'])}%" } ] } ] }, { "tag": "action", "actions": [ { "tag": "button", "text": {"content": "立即处理", "tag": "plain_text"}, "url": metric["console_url"], "type": "primary" } ] } ] }在实际项目中使用这些技术时，建议将卡片模板抽象为可配置的JSON文件或数据库存储，结合模板引擎实现动态内容渲染。对于高频发送场景，可以考虑引入消息队列和批量发送机制优化性能。