# Miro API 技能使用 REST API v2 和 Python SDK 掌握 Miro 白板自动化。该技能涵盖板创建、小部件管理、框架、形状、连接器、模板和用于构建自动化视觉工作流程的实时协作模式。 ## 何时使用此技能 ### 在以下情况下使用： * 自动创建冲刺回顾板 * 构建可视化项目状态仪表板 * 创建自动化架构图 * 设置模板化的研讨会板 * 将 Miro 与 CI/CD 管道集成 * 自动化用户故事映射工作流程 * 创建可视化事件响应板 * 构建自动化入职板 * 生成会议引导模板 * 将外部系统的数据同步到Miro ### 不要在以下情况下使用： * 简单的基于文本的协作（使用 Slack 或 Teams） * 以文档为中心的工作流程（使用 Notion 或 Confluence） * 以代码为中心的图表（使用 Mermaid 或 PlantUML） * 实时白板，无需持久化 * 个人笔记（使用黑曜石） ## 先决条件 ### Miro 应用程序设置 # 1. 在 https://miro.com/app/settings/user-profile/apps 创建一个 Miro 应用程序 # 2.选择REST API 2.0 # 3. 配置 OAuth 2.0 范围 # 所需的 OAuth 范围： # - Boards:read - 读取主板数据 # - Boards:write - 创建和修改板 # - team:read - 读取团队信息 # - Identity:read - 读取用户身份 # - 麦克风：读取 - 读取板音频（可选） # - screen_recording - 屏幕录制（可选） # 不同用例的应用程序权限： # 团队应用程序：板：读，板：写，团队：读 # 用户应用程序：boards:read、boards:write、identity:read # 管理应用程序：所有范围+组织管理 # 通过 OAuth 2.0 获取访问令牌： # 1. 将用户重定向到：https://miro.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI # 2. 将代码兑换为令牌：https://api.miro.com/v1/oauth/token ### Python环境设置 # 创建虚拟环境 python -m venv miro-env 源 miro-env/bin/activate # Linux/macOS # miro-env\Scripts\activate # Windows # 安装 Miro API SDK pip 安装 miro-api # 安装额外的依赖项 pip install python-dotenv 请求 httpx aiohttp # 创建需求.txt 猫 > 要求.txt << 'EOF' miro-api>=2.0.0 python-dotenv>=1.0.0 请求>=2.31.0 httpx>=0.25.0 aiohttp>=3.9.0 枕头>=10.0.0 EOF # 环境变量猫 > .env << 'EOF' MIRO_ACCESS_TOKEN=您的访问令牌 MIRO_CLIENT_ID=您的客户 ID MIRO_CLIENT_SECRET=您的客户秘密 MIRO_TEAM_ID=您的团队 ID EOF ### API 认证 # 验证.py # 关于我：Miro API 身份验证实用程序 # ABOUTME：处理 OAuth2 令牌管理和刷新导入操作系统从 dotenv 导入 load_dotenv 导入请求从日期时间导入日期时间，时间增量加载_dotenv() 类 MiroAuth： """Miro OAuth2 身份验证处理程序""" BASE_URL =“https://api.miro.com” AUTH_URL =“https://miro.com/oauth/authorize” TOKEN_URL =“https://api.miro.com/v1/oauth/token” def __init__(自身): self.client_id = os.environ.get("MIRO_CLIENT_ID") self.client_secret = os.environ.get("MIRO_CLIENT_SECRET") self.access_token = os.environ.get("MIRO_ACCESS_TOKEN") self.refresh_token = os.environ.get("MIRO_REFRESH_TOKEN") self.token_expires = 无 def get_authorization_url(self, redirect_uri: str, state: str = None) -> str: """生成 OAuth2 授权 URL""" 参数 = { “response_type”：“代码”， “client_id”：self.client_id， “redirect_uri”：redirect_uri， } 如果状态：参数[“状态”] = 状态 query = "&".join(f"{k}={v}" for k, v in params.items()) 返回f“{self.AUTH_URL}？{query}” def Exchange_code_for_token(self, 代码: str, redirect_uri: str) -> 字典: """用授权码交换访问令牌""" 响应 = requests.post( self.TOKEN_URL, 数据={ "grant_type": "授权码", “client_id”：self.client_id， “client_secret”：self.client_secret， “代码”：代码， “redirect_uri”：redirect_uri， }, ）响应.raise_for_status() token_data = 响应.json() self.access_token = token_data["access_token"] self.refresh_token = token_data.get("refresh_token") self.token_expires = datetime.now() + timedelta( 秒= token_data.get("expires_in", 3600) ）返回token_data def refresh_access_token(self) -> 字典： """刷新访问令牌""" 响应 = requests.post( self.TOKEN_URL, 数据={ "grant_type": "refresh_token", “client_id”：self.client_id， “client_secret”：self.client_secret， “refresh_token”：self.refresh_token， }, ）响应.raise_for_status() token_data = 响应.json() self.access_token = token_data["access_token"] self.refresh_token = token_data.get("refresh_token", self.refresh_token) 返回token_data def get_headers(self) -> 字典： """获取 API 请求的授权标头""" 返回{ "授权": f"承载{self.access_token}", “内容类型”：“应用程序/json”， } ## 核心能力 ### 1\.董事会管理 # 板子.py # 关于我：Miro 董事会管理运营 # 关于我：创建、读取、更新、删除版块导入操作系统从 miro_api 导入 Miro 从 dotenv 导入 load_dotenv 加载_dotenv() # 初始化 Miro 客户端 miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def create_board(名称: str, 描述: str = "", team_id: str = None) -> dict: """创建一个新的 Miro 板""" team_id = team_id 或 os.environ.get("MIRO_TEAM_ID") 板 = miro.boards.create( 姓名=姓名，描述=描述， team_id=team_id, 政策={ “权限策略”：{ "collaborationToolsStartAccess": "all_editors", “copyAccess”：“任何人”， "sharingAccess": "team_members_with_editing_rights", }, “共享政策”：{ “访问”：“私人”， "inviteToAccountAndBoardLinkAccess": "编辑器", “组织访问”：“私人”， "teamAccess": "编辑", }, }, ）返回{ “id”：板.id， “名称”：董事会名称， “view_link”：board.view_link， “created_at”：board.created_at， } def get_board(board_id: str) -> 字典： """获取主板详细信息""" 板 = miro.boards.get(board_id) 返回{ “id”：板.id， “名称”：董事会名称， “描述”：板.描述， “view_link”：board.view_link， “created_at”：board.created_at， “modified_at”：board.modified_at， } def list_boards(team_id: str = None, limit: int = 50) -> 列表: """列出团队中的所有面板""" team_id = team_id 或 os.environ.get("MIRO_TEAM_ID") 板 = miro.boards.get_all(team_id=team_id, limit=limit) 返回[ { “id”：板.id， “名称”：董事会名称， “view_link”：board.view_link， } 用于板中板 ] def update_board(board_id: str, 名称: str = None, 描述: str = None) -> dict: """更新板属性""" 更新数据 = {} 如果名称： update_data[“名称”] = 名称如果描述： update_data[“描述”] = 描述 board = miro.boards.update(board_id, **update_data) return {"id": board.id, "name": board.name, "description": board.description} def delete_board(board_id: str) -> bool: """删除板块""" miro.boards.delete(board_id) 返回真 def copy_board(board_id: str, new_name: str, team_id: str = None) -> dict: """复制现有板""" team_id = team_id 或 os.environ.get("MIRO_TEAM_ID") board = miro.boards.copy(board_id, name=new_name, team_id=team_id) 返回{ “id”：板.id， “名称”：董事会名称， “view_link”：board.view_link， } # 使用示例如果 __name__ == "__main__": # 创建一个板板=创建_板（ name="Sprint 回顾 - 2026 年第一季度", description="Q1 sprint 团队回顾", ） print(f"已创建板：{board['view_link']}") # 列出板块板= list_boards（限制= 10）对于板中的 b： print(f"- {b['name']}: {b['view_link']}") ### 2\.便利贴和卡片 # Sticky_notes.py # 关于我：便签和卡片创建 # 关于我：创建、定位和设置便签样式从 miro_api 导入 Miro 导入操作系统 miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def create_sticky_note( board_id：str，内容：str， x：浮点= 0， y：浮点= 0，颜色：str =“黄色”，宽度：浮动= 200， ) -> 字典： """在板上创建便签""" # 颜色映射颜色={ “黄色”：“黄色”， “绿色”：“绿色”， “蓝色”：“蓝色”， “粉红色”：“粉红色”， “橙色”：“橙色”， “紫色”：“紫罗兰色”， “灰色”：“灰色”， “青色”：“青色”， “红色”：“红色”， "浅黄色": "浅黄色", "light_green": "light_green", "浅蓝色": "浅蓝色", "浅粉色": "浅粉色", } 粘性 = miro.sticky_notes.create( board_id=board_id, data={"content": 内容, "shape": "正方形"}, style={"fillColor": color.get(color, "yellow")}, 位置={“x”：x，“y”：y，“原点”：“中心”}，几何={“宽度”：宽度}，）返回{ “id”：粘性ID， “内容”：粘性数据.内容， “位置”：{“x”：粘性位置.x，“y”：粘性位置.y}， “颜色”：sticky.style.fill_color， } def create_sticky_grid( board_id：str，项目：列表，开始_x：浮动= 0， start_y：浮点= 0，列：int = 4，间距：浮动= 250，颜色：str =“黄色”， ) -> 列表： """创建便签网格""" 创建=[] 对于 i，枚举中的项目（项目）：行 = i // 列 col = i % 列 x = start_x + (列 * 间距) y = start_y + (行 * 间距) 粘性 = create_sticky_note( board_id=board_id，内容=项目，x=x，y=y，颜色=颜色）创建.追加（粘性）返回已创建 def 创建卡( board_id：str，标题：str，描述：str = "", x：浮点= 0， y：浮点= 0，受让人_id：str = 无， due_date：str =无，标签：列表=无， ) -> 字典： """创建卡片小部件""" card_data = {“标题”：标题，“描述”：描述} 如果受让人_id：卡数据[“分配者 ID”] =分配者 ID 如果到期日期：卡数据[“到期日期”] = 到期日期如果标签： card_data["tagIds"] = 标签卡 = miro.cards.create( board_id=board_id, 数据=卡数据，位置={“x”：x，“y”：y，“原点”：“中心”}，几何={“宽度”：320，“高度”：200}，）返回{ “id”：卡ID， “标题”：卡片.数据.标题， "position": {"x": 卡.position.x, "y": 卡.position.y}, } def update_sticky_note( board_id：str，sticky_id：str，内容：str = None，颜色：str = None ) -> 字典： """更新便签""" 更新数据 = {} 如果内容： update_data["数据"] = {"内容": 内容} 如果颜色： update_data["style"] = {"fillColor": 颜色} Sticky = miro.sticky_notes.update(board_id, Sticky_id, **update_data) 返回{“id”：sticky.id，“content”：sticky.data.content} def delete_sticky_note(board_id: str, Sticky_id: str) -> bool: """删除便签""" miro.sticky_notes.delete(board_id, Sticky_id) 返回真 # 回顾板示例 def create_retro_board(board_id: str) -> dict: """创建回顾性的董事会布局""" # 创建类别标题类别 = [ {"title": "进展顺利", "color": "绿色", "x": 0}, {"title": "需要改进什么", "color": "粉色", "x": 500}, {"title": "行动项目", "color": "蓝色", "x": 1000}, ] 创建的_stickies = {} 对于类别中的猫： # 创建标题粘性标题=创建_粘性_笔记（ board_id=board_id, content=f"{cat['title']}", x=猫[“x”], y=-200，颜色=猫[“颜色”], 宽度=400，）创建的_stickies[cat["标题"]] = [标题] # 创建占位符便签对于范围 (3) 内的 i：占位符 = create_sticky_note( board_id=board_id, content="在这里添加您的想法...", x=猫[“x”], y = i * 150，颜色=猫[“颜色”], ）创建的_stickies[cat["标题"]].append(占位符) 返回create_stickies 如果 __name__ == "__main__": board_id =“您的BOARD_ID” # 创建便签网格 items = [“任务 1”、“任务 2”、“任务 3”、“任务 4”、“任务 5”、“任务 6”] 便利贴 = create_sticky_grid( board_id = board_id，项目=项目，列= 3，颜色=“蓝色” ） print(f"已创建 {len(stickies)} 便笺") ### 3\.形状和绘图 # 形状.py # 关于：形状创建和操作 # 关于我：矩形、圆形、直线和自定义形状从 miro_api 导入 Miro 导入操作系统 miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def create_shape( board_id：str，形状类型：str，内容：str =“”， x：浮点= 0， y：浮点= 0，宽度：浮动= 200，高度：浮动= 100，填充颜色：str =“#ffffff”，边框颜色: str = "#000000", 边框宽度：int = 2， ) -> 字典： """在板上创建一个形状形状类型：矩形、圆形、三角形、菱形、平行四边形、梯形、五边形、六边形、八边形、楔形_圆形_矩形_标注、圆形矩形、星形、流程图进程、流程图决策、 flow_chart_terminator、flow_chart_data、flow_chart_document ”“” 形状 = miro.shapes.create( board_id=board_id, 数据={“内容”：内容，“形状”：shape_type}，风格={ “填充颜色”：填充颜色， “边框颜色”：边框颜色， “边框宽度”：str（边框宽度）， "borderStyle": "正常", "fontFamily": "宋体", “字体大小”：“14”， “文本对齐”：“居中”， "textAlignVertical": "中间", }, 位置={“x”：x，“y”：y，“原点”：“中心”}，几何={“宽度”：宽度，“高度”：高度}，）返回{ “id”：形状.id， “类型”：形状.数据.形状， "position": {"x": shape.position.x, "y": shape.position.y}, } def 创建矩形（ board_id：str，内容：str =“”， x：浮点= 0， y：浮点= 0，宽度：浮动= 200，高度：浮动= 100，填充颜色：str =“#ffffff”， ) -> 字典： """创建一个矩形""" 返回创建形状（ board_id=board_id, shape_type =“矩形”，内容=内容， x=x, y=y, 宽度=宽度，高度=高度，填充颜色=填充颜色，） def create_circle( board_id：str，内容：str =“”， x：浮点= 0， y：浮点= 0，直径：浮动= 100，填充颜色：str =“#ffffff”， ) -> 字典： “”“创建一个圆圈”“” 返回创建形状（ board_id=board_id, shape_type =“圆形”，内容=内容， x=x, y=y, 宽度=直径，高度=直径，填充颜色=填充颜色，） def create_flowchart_shape( board_id：str，形状类型：str，内容：str =“”， x：浮点= 0， y：浮点= 0，宽度：浮动= 150，高度：浮动= 80， ) -> 字典： """创建流程图形状类型：flow_chart_process、flow_chart_decision、flow_chart_terminator、 flow_chart_data、flow_chart_document、flow_chart_predefined_process、 flow_chart_manual_input、flow_chart_display、flow_chart_preparation ”“” 颜色={ "flow_chart_process": "#e3f2fd", "flow_chart_decision": "#fff3e0", "flow_chart_terminator": "#f3e5f5", "flow_chart_data": "#e8f5e9", "flow_chart_document": "#fce4ec", } 返回创建形状（ board_id=board_id, 形状类型=形状类型，内容=内容， x=x, y=y, 宽度=宽度，高度=高度， fill_color=colors.get(shape_type, "#ffffff"), ） def create_flowchart(board_id: str, 步骤: 列表, start_x: float = 0, start_y: float = 0) -> 列表: """从步骤列表创建流程图每一步：{"type": "process|decision|terminator", "content": "text"} ”“” 创建=[] 当前_y = 开始_y 对于步骤： shape_type = f"flow_chart_{step.get('type', 'process')}" 高度 = 100 if step.get("type") == "decision" else 80 形状=创建流程图形状（ board_id=board_id, 形状类型=形状类型，内容=步骤[“内容”], x=开始_x, y=当前_y，高度=高度，）创建.追加（形状） current_y += height + 80 # 添加连接器间距返回已创建 def update_shape( board_id：str，形状 ID：str，内容：str = 无，填充颜色：str = 无， x：浮动=无， y：浮点=无， ) -> 字典： """更新形状""" 更新数据 = {} 如果内容不为 None： update_data["数据"] = {"内容": 内容} 如果填充颜色： update_data["style"] = {"fillColor": fill_color} 如果 x 不是 None 或 y 不是 None：位置={} 如果 x 不是 None：位置[“x”] = x 如果 y 不为 None：位置[“y”] = y update_data["位置"] = 位置形状 = miro.shapes.update(board_id, shape_id, **update_data) 返回 {"id": shape.id} 如果 __name__ == "__main__": board_id =“您的BOARD_ID” # 创建一个简单的流程图步骤= [ {"type": "终结者", "content": "开始"}, {"type": "进程", "content": "初始化系统"}, {"type": "决定", "content": "有效输入？"}, {"type": "过程", "content": "过程数据"}, {"type": "结束符", "content": "结束"}, ] 流程图 = create_flowchart(board_id, 步骤) print(f"使用 {len(flowchart)} 形状创建流程图") ### 4\.连接器和线路 # 连接器.py # 关于我：连接器和线路创建 # 关于我：连接形状、创建箭头和流程图从 miro_api 导入 Miro 导入操作系统 miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def create_connector( board_id：str，起始项目 ID：str，结束项 ID：str，起始位置：str =“右”， end_position: str = "左", 描边颜色: str = "#000000", 笔画宽度：int = 2，笔划样式：str =“正常”， start_cap：str =“无”， end_cap: str = "隐身", 标题：str = 无， ) -> 字典： """在两个项目之间创建连接器位置：上、右、下、左、自动大写字母：无、隐形、rounded_stealth、diamond、diamond_filled、oval、oval_filled、箭头、三角形、triangle_filled、erd_one、erd_many、erd_one_or_many、erd_only_one、 erd_zero_or_one、erd_zero_or_many 笔画样式：普通、虚线、点线 ”“” 连接器数据 = { “startItem”：{“id”：start_item_id，“position”：{“x”：start_position}}， “endItem”：{“id”：end_item_id，“position”：{“x”：end_position}}， } 连接器样式 = { “笔画颜色”：笔画颜色， “笔画宽度”：str（笔画宽度）， “笔划样式”：笔划样式， “startStrokeCap”：start_cap， “endStrokeCap”：end_cap， } 如果标题： Connector_data["captions"] = [{"content": 标题, "position": "50%"}] 连接器 = miro.connectors.create( board_id=board_id, 数据=连接器数据，样式=连接器样式，）返回{ “id”：连接器.id， “start_item”：连接器.start_item.id， “end_item”：连接器.end_item.id， } def 创建线（ board_id：str， start_x：浮动， start_y：浮动， end_x：浮动， end_y：浮动，描边颜色: str = "#000000", 笔画宽度：int = 2， end_cap：str =“无”， ) -> 字典： """创建独立线路""" # 对于没有连接项的线，我们使用绝对坐标连接器 = miro.connectors.create( board_id=board_id, 数据={ "startItem": {"position": {"x": start_x, "y": start_y}}, “endItem”：{“位置”：{“x”：end_x，“y”：end_y}}， }, 风格={ “笔画颜色”：笔画颜色， “笔画宽度”：str（笔画宽度）， "startStrokeCap": "无", “endStrokeCap”：end_cap， }, ）返回 {"id": 连接器.id} def connect_flowchart_shapes(board_id: str, shape_ids: list, labels: list = None) -> list: """按顺序连接形状列表""" 创建=[] 对于范围内的 i(len(shape_ids) - 1)： label = labels[i] 如果 labels 且 i < len(labels) 否则 None 连接器 = 创建连接器（ board_id=board_id, start_item_id=shape_ids[i], end_item_id=shape_ids[i + 1], start_position =“底部”， end_position =“顶部”， end_cap =“隐形”，标题=标签，）创建.追加（连接器）返回已创建 def create_decision_branches( board_id：str， Decision_shape_id：str， yes_shape_id：str， no_shape_id：str， ) -> 列表： """从决策菱形创建是/否分支""" yes_connector = 创建_connector( board_id=board_id, start_item_id=decision_shape_id, end_item_id=yes_shape_id, start_position =“底部”， end_position =“顶部”， end_cap =“隐形”，标题=“是”，笔划颜色=“#4caf50”，）没有连接器 = 创建连接器（ board_id=board_id, start_item_id=decision_shape_id, end_item_id=no_shape_id, start_position =“右”， end_position =“左”， end_cap =“隐形”，标题=“不”，笔划颜色=“#f44336”，）返回 [yes_connector, no_connector] def create_erd_relationship( board_id：str，实体1_id：str，实体2_id：str， cardinality_start: str = "erd_one", cardinality_end: str = "erd_many", 标签：str = 无， ) -> 字典： """创建 ERD 关系线基数：erd_one、erd_many、erd_one_or_many、erd_only_one、 erd_zero_or_one、erd_zero_or_many ”“” 返回创建连接器（ board_id=board_id, start_item_id=entity1_id, end_item_id=entity2_id, start_cap=cardinality_start, end_cap=基数结束，标题=标签，） def update_connector( board_id：str，连接器_id：str，描边颜色：str = 无，标题：str = 无， ) -> 字典： """更新连接器""" 更新数据 = {} 如果笔画颜色： update_data[“样式”] = {“笔划颜色”：笔划颜色} 如果标题： update_data["标题"] = [{"内容": 标题, "位置": "50%"}] 连接器= miro.connectors.update（board_id，connector_id，**update_data）返回 {"id": 连接器.id} def delete_connector(board_id: str,connector_id: str) -> bool: """删除连接器""" miro.connectors.delete（board_id，connector_id）返回真如果 __name__ == "__main__": board_id =“您的BOARD_ID” # 示例：连接形状 shape_ids = [“shape1_id”，“shape2_id”，“shape3_id”] 连接器= connect_flowchart_shapes(board_id, shape_ids) print(f"已创建 {len(connectors)} 连接器") ### 5\.框架和组织 # 帧.py # 关于我：董事会组织框架创建 # 关于我：对项目进行分组、创建部分并管理布局从 miro_api 导入 Miro 导入操作系统从输入导入列表，可选 miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def create_frame( board_id：str，标题：str， x：浮点= 0， y：浮点= 0，宽度：浮动= 800，高度：浮动= 600，填充颜色：str =“#f5f5f5”， ) -> 字典： """创建一个框架来组织看板内容""" 框架 = miro.frames.create( board_id=board_id, data={"title": 标题, "format": "自定义"}, 样式={"fillColor": fill_color}, 位置={“x”：x，“y”：y，“原点”：“中心”}，几何={“宽度”：宽度，“高度”：高度}，）返回{ "id": 框架.id, “标题”：框架.数据.标题， "position": {"x":frame.position.x, "y":frame.position.y}, "几何": {"宽度":frame.geometry.width, "高度":frame.geometry.height}, } def create_frame_grid( board_id：str，标题：列表，列：int = 3，框架宽度：浮动= 600，框架高度：浮动= 400，间距：浮动= 50，开始_x：浮动= 0， start_y：浮点= 0， ) -> 列表： """创建框架网格""" 创建=[] 对于 i，枚举中的标题（标题）：行 = i // 列 col = i % 列 x = start_x + col * (frame_width + 间距) y = start_y + 行 * (frame_height + 间距) 框架 = 创建框架（ board_id=board_id, 标题=标题， x=x, y=y, 宽度=框架宽度，高度=框架高度，）创建.追加（框架）返回已创建 def create_kanban_board( board_id：str，列：列表=无，框架宽度：浮动= 400，框架高度：浮动= 800， ) -> 列表： """创建带有列的看板式看板""" 如果列为无： columns = [“待办事项”、“进行中”、“审核”、“完成”] 颜色={ “待办事项”：“#f5f5f5”， “进行中”：“#fff3e0”， “评论”：“#e8f5e9”， “完成”：“#e3f2fd”， } 帧=[] 开始_x = 0 对于 i，枚举中的列（列）：框架 = 创建框架（ board_id=board_id, 标题=列， x=start_x + i * (frame_width + 50), y=0，宽度=框架宽度，高度=框架高度， fill_color=colors.get(列, "#f5f5f5"), ）框架.追加（框架）返回帧 def create_workshop_layout( board_id：str，sections：列表，section_width：float = 1000，section_height：float = 600 ) -> 字典： """创建车间板布局部分：{“标题”：“名称”，“描述”：“desc”，“颜色”：“#hex”}列表 ”“” 创建= {“框架”：[]，“标题”：[]} 对于 i，枚举中的节（节）： # 为部分创建框架框架 = 创建框架（ board_id=board_id, 标题=节[“标题”], x=0, y=i * (section_height + 100), 宽度=节宽度，高度=截面高度， fill_color=section.get("颜色", "#f5f5f5"), ）创建[“框架”].append(框架) 返回已创建 def update_frame( board_id：str，框架 ID：str，标题：str = 无，宽度：浮动=无，高度：浮动=无， ) -> 字典： """更新框架""" 更新数据 = {} 如果标题： update_data["数据"] = {"标题": 标题} 如果宽度或高度：几何={} 如果宽度：几何形状[“宽度”] = 宽度如果高度：几何[“高度”] = 高度 update_data["几何图形"] = 几何图形框架= miro.frames.update（board_id，frame_id，** update_data） return {"id":frame.id, "title":frame.data.title} def get_items_in_frame(board_id: str, frame_id: str) -> 列表: """获取框架内包含的所有项目""" 框架= miro.frames.get(board_id,frame_id) # 获取子项目孩子= miro.frames.get_children（board_id，frame_id）返回[ {“id”：child.id，“type”：child.type} 为了孩子中的孩子 ] def add_items_to_frame(board_id: str, frame_id: str, item_ids: list) -> bool: """通过更新其父项将项目添加到框架""" 对于 item_ids 中的 item_id： # 框架内的项目通过其位置进行管理 # 它们需要在框架的边界内通过返回真 def delete_frame(board_id: str, frame_id: str) -> bool: """删除帧""" miro.frames.delete(board_id,frame_id) 返回真如果 __name__ == "__main__": board_id =“您的BOARD_ID” # 创建看板看板 = create_kanban_board(board_id) print(f"使用 {len(kanban)} 列创建看板") # 创建车间布局部分= [ {"title": "简介", "color": "#e3f2fd"}, {"title": "头脑风暴", "color": "#fff3e0"}, {"title": "投票", "color": "#e8f5e9"}, {"title": "行动项目", "color": "#f3e5f5"}, ] 车间 = create_workshop_layout(board_id, 部分) print(f"用 {len(workshop['frames'])} 部分创建了研讨会") ### 6\.文字与图像 # 文本图像.py # 关于：文本元素和图像处理 # 关于我：创建文本框、嵌入图像和管理媒体从 miro_api 导入 Miro 导入操作系统导入请求从 io 导入 BytesIO miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def 创建文本( board_id：str，内容：str， x：浮点= 0， y：浮点= 0，宽度：浮动= 200，字体大小：int = 14， font_family: str = "宋体", text_align: str = "左", 颜色：str =“#000000”， ) -> 字典： """创建文本元素""" 文本 = miro.texts.create( board_id=board_id, 数据={“内容”：内容}，风格={ “颜色”：颜色， “填充不透明度”：“1.0”， “fontFamily”：font_family， “字体大小”：str（字体大小）， “文本对齐”：文本对齐， }, 位置={“x”：x，“y”：y，“原点”：“中心”}，几何={“宽度”：宽度}，）返回{ “id”：文本.id， “内容”：文本.数据.内容， "position": {"x": text.position.x, "y": text.position.y}, } def 创建标题( board_id：str，内容：str， x：浮点= 0， y：浮点= 0，级别：int = 1， ) -> 字典： """创建标题文本元素""" 字体大小 = {1: 36, 2: 28, 3: 22, 4: 18} font_size = font_sizes.get(级别, 14) 返回创建文本（ board_id=board_id, 内容=f"{内容}", x=x, y=y, 宽度=500，字体大小=字体大小，） def create_bullet_list( board_id：str，项目：列表， x：浮点= 0， y：浮点= 0， ) -> 字典： """创建项目符号列表""" content = "

{item}

" 返回创建文本（ board_id=board_id, 内容=内容， x=x, y=y, 宽度=400，） def upload_image_from_url( board_id：str，图片网址：str， x：浮点= 0， y：浮点= 0，宽度：浮动=无，标题：str = 无， ) -> 字典： """从 URL 创建图像""" image_data = {“url”：image_url} 如果标题： image_data["标题"] = 标题几何={} 如果宽度：几何形状[“宽度”] = 宽度图像 = miro.images.create( board_id=board_id, 数据=图像数据，位置={“x”：x，“y”：y，“原点”：“中心”}，几何=几何如果几何否则无，）返回{ “id”：图像.id， "position": {"x": image.position.x, "y": image.position.y}, } def upload_image_from_file( board_id：str，文件路径：str， x：浮点= 0， y：浮点= 0，宽度：浮动=无， ) -> 字典： """从本地文件上传图像""" 将 open(file_path, "rb") 作为 f：图像数据 = f.read() # 使用图片上传端点标题= { "授权": f"承载{os.environ.get('MIRO_ACCESS_TOKEN')}", } 文件= {“资源”：（os.path.basename（文件路径），图像数据）} 数据 = {“位置”：f'{{“x”：{x}，“y”：{y}，“原点”：“中心”}}'} 如果宽度：数据[“几何”] = f'{{“宽度”：{宽度}}}' 响应 = requests.post( f“https://api.miro.com/v2/boards/{board_id}/images”，标题=标题，文件=文件，数据=数据，）响应.raise_for_status() 返回response.json() def create_embed( board_id：str，网址：str， x：浮点= 0， y：浮点= 0，宽度：浮动= 400，高度：浮动= 300，模式：str =“模态”， ) -> 字典： """创建嵌入内容（网页、视频等）模式：内联、模态 ”“” 嵌入 = miro.embeds.create( board_id=board_id, data={"url": url, "mode": 模式}, 位置={“x”：x，“y”：y，“原点”：“中心”}，几何={“宽度”：宽度，“高度”：高度}，）返回{ “id”：嵌入.id， “url”：嵌入.data.url， "position": {"x": embed.position.x, "y": embed.position.y}, } def create_document_section( board_id：str，标题：str，描述：str，项目：列表， x：浮点= 0， y：浮点= 0， ) -> 字典： """创建一个类似文档的部分，其中包含标题、描述和要点""" 创建={} # 创建标题标题 = create_heading(board_id, 标题, x=x, y=y, 级别=2) 创建[“标题”] = 标题 # 创建描述 desc = create_text(board_id, 描述, x=x, y=y + 60, 宽度=500) 创建[“描述”] = desc # 创建项目符号列表项目符号 = create_bullet_list(board_id, 项目, x=x, y=y + 150) 创建[“项目”] = 项目符号返回已创建如果 __name__ == "__main__": board_id =“您的BOARD_ID” # 创建文档部分部分=创建_文档_部分( board_id=board_id, title="项目概述", description="该项目旨在通过自动化的 Miro 工作流程来改善团队协作。", 项目=[ “自动创建板”， “基于模板的布局”， “与 CI/CD 集成”， ], ） print(f"使用 {len(section)} 元素创建节") ## 集成示例 ### GitHub 操作集成 # .github/workflows/miro-sync.yml 名称：同步到 Miro 于：问题：类型：[打开，贴标签] 拉请求：类型：[打开、关闭、合并] 职位：同步米罗：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v4 - 名称：设置Python 使用：actions/setup-python@v5 与： python-版本：'3.12' - 名称：安装依赖项运行： | pip install miro-api 请求 - 名称：在 Miro 中创建发行卡 if: github.event_name == '问题' 环境： MIRO_ACCESS_TOKEN：${{secrets.MIRO_ACCESS_TOKEN }} MIRO_BOARD_ID：${{ Secrets.MIRO_BOARD_ID }} 运行： | 蟒蛇 << 'EOF' 导入操作系统从 miro_api 导入 Miro miro = Miro(access_token=os.environ["MIRO_ACCESS_TOKEN"]) board_id = os.environ["MIRO_BOARD_ID"] # 为新问题创建便签 issues_title = "${{ github.event.issue.title }}" issues_number = "${{ github.event.issue.number }}" issues_url = "${{ github.event.issue.html_url }}" miro.sticky_notes.create( board_id=board_id, 数据={ “内容”：f“#{issue_number}：{issue_title}\n\n{issue_url}” }, 样式={"fillColor": "黄色"}, 位置={"x": 0, "y": 0, "原点": "中心"}, ） print(f"已为问题 #{issue_number} 创建便签") EOF - 名称：更新 Miro 中的 PR 状态 if: github.event_name == 'pull_request' 环境： MIRO_ACCESS_TOKEN：${{secrets.MIRO_ACCESS_TOKEN }} MIRO_BOARD_ID：${{ Secrets.MIRO_BOARD_ID }} 运行： | 蟒蛇 << 'EOF' 导入操作系统从 miro_api 导入 Miro miro = Miro(access_token=os.environ["MIRO_ACCESS_TOKEN"]) board_id = os.environ["MIRO_BOARD_ID"] pr_title = "${{ github.event.pull_request.title }}" pr_state = "${{ github.event.action }}" 颜色={ “打开”：“light_blue”， “关闭”：“红色”， “合并”：“绿色”， } miro.sticky_notes.create( board_id=board_id, data={"content": f"PR: {pr_title}\n状态: {pr_state}"}, style={"fillColor": color.get(pr_state, "gray")}, 位置={“x”：500，“y”：0，“原点”：“中心”}，） EOF ### Sprint 回顾自动化 # 复古自动化.py # 关于我：自动创建冲刺回顾板 # 关于我：创建带有类别的模板化复古板从 miro_api 导入 Miro 导入操作系统从日期时间导入日期时间 miro = Miro(access_token=os.environ.get("MIRO_ACCESS_TOKEN")) def create_retrospective_board( sprint_number：整数，团队名称：str， team_id: str = 无, ) -> 字典： """为冲刺创建一个完整的回顾板""" team_id = team_id 或 os.environ.get("MIRO_TEAM_ID") # 创建板 board_name = f“Sprint {sprint_number} 回顾 - {team_name}” 板 = miro.boards.create( 名称=板名称， description=f"Sprint {sprint_number} 回顾", team_id=team_id, ） board_id = 板.id # 为类别创建框架类别 = [ {"title": "进展顺利", "color": "#c8e6c9", "x": 0}, {"title": "需要改进的地方", "color": "#ffcdd2", "x": 700}, {"title": "行动项目", "color": "#bbdefb", "x": 1400}, ] 帧=[] 对于类别中的猫：框架 = miro.frames.create( board_id=board_id, data={"title": cat["title"], "format": "custom"}, 样式={"fillColor": cat["color"]}, 位置={“x”：cat[“x”]，“y”：0，“原点”：“中心”}，几何={“宽度”：600，“高度”：800}，） frames.append({"id":frame.id, "title":cat["title"]}) # 添加占位符贴纸对于范围 (3) 内的 i： miro.sticky_notes.create( board_id=board_id, data={"content": "在此添加您的想法..."}, 样式={"fillColor": cat["color"]}, 位置={ “x”：猫[“x”]， “y”：-200 +（i * 150）， “原点”：“中心”， }, ） # 创建标题 miro.texts.create( board_id=board_id, 数据={ "content": f"Sprint {sprint_number} 回顾
{datetime.now().strftime('%B %d, %Y')}" }, style={"fontSize": "36", "textAlign": "center"}, 位置={“x”：700，“y”：-500，“原点”：“中心”}，几何={“宽度”：800}，） # 添加投票指令 miro.texts.create( board_id=board_id, 数据={ "content": "说明：
1. 向每个类别添加便签
2. 使用点对项目进行投票
3. 讨论投票最多的项目
4. 创建操作项目" }, 样式={"fontSize": "14"}, 位置={“x”：-400，“y”：0，“原点”：“中心”}，几何={“宽度”：300}，）返回{ “board_id”：board_id， “view_link”：board.view_link， “框架”：框架， } def create_sprint_planning_board( sprint_number：整数，团队名称：str，故事：列表， ) -> 字典： """创建包含用户故事的冲刺计划板""" 板 = miro.boards.create( name=f"Sprint {sprint_number} 规划 - {team_name}", description=f"Sprint {sprint_number} 规划委员会", team_id=os.environ.get("MIRO_TEAM_ID"), ） board_id = 板.id # 创建看板列 columns = [“待办事项”、“待办事项”、“进行中”、“审核”、“完成”] 列宽度 = 350 列高度 = 1000 对于 i，枚举中的 col（列）： miro.frames.create( board_id=board_id, data={"标题": col, "格式": "自定义"}, 样式={"fillColor": "#f5f5f5"}, 位置={“x”：i *（col_width + 30），“y”：0，“原点”：“中心”}，几何={“宽度”：col_width，“高度”：col_height}，） # 将故事添加到待办事项中对于 j，枚举中的故事（故事）： miro.cards.create( board_id=board_id, 数据={ "标题":story.get("标题","用户故事"), “描述”：story.get(“描述”,“”), }, 位置={"x": 0, "y": -300 + (j * 150), "原点": "中心"}, 几何={“宽度”：300，“高度”：120}，）返回{“board_id”：board_id，“view_link”：board.view_link} 如果 __name__ == "__main__": # 创建回顾板 Retro = create_retrospective_board(sprint_number=15, team_name="平台团队") print(f"复古板：{retro['view_link']}") # 创建计划板故事=[ {"title": "作为用户，我想使用SSO登录", "description": "实现SSO认证"}, {"title": "作为用户，我想要深色模式", "description": "添加深色模式支持"}, ] Planning = create_sprint_planning_board(sprint_number=16, team_name="平台团队", Stories=stories) print(f"规划板：{planning['view_link']}") ## 最佳实践 ### 1\.速率限制 # 速率限制处理导入时间从 functools 导入包装 defrate_limit_handler(max_retries=3, base_delay=1): """用于处理 Miro 速率限制的装饰器""" def 装饰器（函数）： @wraps(函数) def 包装器（*args，**kwargs）：对于范围内的尝试（max_retries）：尝试：返回 func(*args, **kwargs) 除了异常 e：如果 str(e) 中为“429”或 str(e).lower() 中为“rate”：延迟 = base_delay * (2 ** 尝试) print(f"速率有限，等待{延迟}s...") 时间.睡眠（延迟）其他：提高引发异常（“超出最大重试次数”）返回包装器返回装饰器 @rate_limit_handler(最大重试次数=3) def safe_create_sticky(board_id, 内容, x, y): 返回 miro.sticky_notes.create( board_id=board_id, 数据={“内容”：内容}，位置={“x”：x，“y”：y，“原点”：“中心”}，） ### 2\.批量操作 # 批量创建以获得更好的性能 defbatch_create_stickies（board_id：str，项目：列表，batch_size：int = 10）： """批量创建便签以避免速率限制""" 创建=[] 对于范围内的 i（0，len（项目），batch_size）：批次 = 项目[i:i + 批次大小] 对于批量项目：粘性 = miro.sticky_notes.create( board_id=board_id, 数据={“内容”：项目[“内容”]}， style={"fillColor": item.get("color", "yellow")}, 位置={“x”：项目[“x”]，“y”：项目[“y”]，“原点”：“中心”}，）创建.追加（粘性） # 批次之间的延迟很小如果 i + 批量大小 < len(items)：睡眠时间(0.5) 返回已创建 ### 3\.错误处理 # 全面的错误处理从 miro_api.exceptions 导入 MiroApiException def safe_api_call(func, *args, **kwargs): """安全 API 调用的包装器""" 尝试：返回 func(*args, **kwargs) 除了 MiroApiException 为 e：如果 e.status_code == 404： print(f"未找到资源：{e}") 返回无 elif e.status_code == 401： print("身份验证失败 - 检查令牌") 提高 elif e.status_code == 403： print("权限被拒绝 - 检查范围") 提高 elif e.status_code == 429： print("速率限制-实施退避") 时间.睡眠(60) 返回 func(*args, **kwargs) 其他：提高 ### 4\.位置计算 # 用于定位的辅助函数 defcalculate_grid_position（索引：int，列：int，间距：float = 250）： """计算网格布局的 x, y""" 行=索引//列 col = 索引 % 列返回{ “x”：列 * 间距， “y”：行*间距， } def计算圆位置（索引：int，总计：int，半径：float = 300，center_x：float = 0，center_y：float = 0）： """计算圆形布局的 x, y""" 导入数学角度 = (2 * math.pi * 索引) / 总计返回{ "x": center_x + 半径 * math.cos(角度), "y": center_y + 半径 * math.sin(角度), } ## 故障排除 ### 常见问题 **问题：401 未经授权** # 验证token是否有效导入请求 def verify_token(令牌: str) -> bool: 响应 = requests.get( “https://api.miro.com/v1/users/me”， headers={"Authorization": f"Bearer {token}"} ）返回响应.status_code == 200 # 检查令牌范围 def get_token_scopes(token: str) -> 列表：响应 = requests.get( “https://api.miro.com/v1/oauth-token”， headers={"Authorization": f"Bearer {token}"} ）返回response.json().get("范围", []) **问题：物品未出现在船上** # 检查板子权限 def check_board_access(board_id: str) -> 字典: 板 = miro.boards.get(board_id) 返回{ “id”：板.id， “权限”：board.policy.permissions_policy， “共享”：board.policy.sharing_policy， } **问题：速率限制** # 实现指数退避导入时间 def with_backoff(func, max_retries=5): 对于范围内的 i（最大重试次数）：尝试：返回函数() 除了异常 e：如果 str(e) 中为“429”：等待 = (2 ** i) + (random.random() * 0.1) 时间.睡眠（等待）其他：提高引发异常（“超出最大重试次数”） ### 调试命令 # 测试API认证卷曲-X GET“https://api.miro.com/v1/users/me”\ -H“授权：持有者$MIRO_ACCESS_TOKEN” # 列出板块卷曲-X GET“https://api.miro.com/v2/boards?team_id=$MIRO_TEAM_ID”\ -H“授权：持有者$MIRO_ACCESS_TOKEN” # 获取棋盘详细信息卷曲-X GET“https://api.miro.com/v2/boards/$BOARD_ID”\ -H“授权：持有者$MIRO_ACCESS_TOKEN” # 创建便签卷曲-X POST“https://api.miro.com/v2/boards/$BOARD_ID/sticky_notes”\ -H“授权：持有者$MIRO_ACCESS_TOKEN”\ -H“内容类型：application/json”\ -d '{"data": {"content": "测试笔记"}, "position": {"x": 0, "y": 0}}' ## 版本历史版本 |日期 |变化 ---|---|--- 1.0.0 | 2026-01-17 |具有全面 Miro API v2 模式的初始版本 ## 资源 * [Miro REST API 文档]() * [Miro Python SDK]() * [Miro 开发者门户]() * [OAuth 2.0 指南]() * [Webhooks 文档]() * [速率限制]() ** ** _此技能为 Miro 白板自动化提供生产就绪模式，从而实现强大的可视化协作工作流程和团队生产力工具。_

米罗·阿皮

包含技能