mage-ai 集成 Monday 数据源：配置 api_token、board_limit 与五大 GraphQL 数据流详解

数据工程数据编排ETL任务调度批处理流处理数据集成后端【免费下载链接】mage-ai Build, run, and manage data pipelines for integrating and transforming data.项目地址https://gitcode.com/gh_mirrors/ma/mage-ai点击查看免费下载本篇文章基于开源仓库 mage-ai 中mage_integrations/mage_integrations/sources/monday的官方连接器说明深入讲解如何在 Mage 数据集成Data Integration管道中接入 Mondaymonday.com作为数据源包括api_token、board_id、board_limit三个核心配置项的作用与取值、API Token 的获取方式以及该连接器内部通过 GraphQL 查询实现的boards、workspaces、groups、columns、board_views五大数据流stream及其分页、Schema 与错误处理机制。阅读本文后你将能够在自己的 Mage 项目中完整配置并运行 Monday 数据源同步任务。Monday 数据源在 mage-ai 中的定位Mage 数据集成框架mage_integrations将“源Source”定义为“你希望从中加载数据并同步到另一个系统的外部系统”Monday 就是官方提供的一个 SaaS 类数据源用于将 monday.com 上的看板Board、工作区Workspace、分组Group、列Column和视图View等数据抽取出来供下游数据管道使用。你可以在 docs/data-integrations/overview.mdx 的 “Sources” 一节中看到它与其他数据源的并列关系。从仓库结构看该连接器的完整实现位于入口与数据加载逻辑mage_integrations/mage_integrations/sources/monday/init.pyHTTP 客户端封装mage_integrations/mage_integrations/sources/monday/client.py数据流定义mage_integrations/mage_integrations/sources/monday/streams.py各数据流的 JSON Schemamage_integrations/mage_integrations/sources/monday/schemas/配置模板mage_integrations/mage_integrations/sources/monday/templates/config.json必需配置项api_token、board_id 与 board_limit配置 Monday 数据源时必须提供以下凭据与参数下表来自连接器 README 与配置模板Key描述示例值api_token用于身份认证的 API Token。abcdefghijklmnopqrstuvwxyzboard_id用于查询看板board相关数据的看板 ID。12345678board_limitboards数据流中每页返回的看板数量。25其中board_limit在 templates/config.json 中默认值为25board_id默认为null即不指定具体看板由boards查询动态发现。三个配置项在源码中的实际作用api_token在 client.py 中Client.get_headers()直接以Authorization: api_token请求头方式透传给 Monday API因此该 Token 必须具备读取看板、分组、列、视图等对象的权限范围。board_id虽然它出现在配置项中但从源码看groups、columns、board_views这三个子数据流实际使用的看板 ID 来自父数据流boards动态下发的board_id见后文“父子数据流”一节board_id配置项更多用于显式限定查询范围或配合上游配置使用。board_limit直接影响boards数据流的 GraphQL 查询变量与分页行为。在 streams.py 中BoardsStream.get_url_params()会将board_limit作为board_limit变量传入查询同时 get_next_page_token() 判断“本页返回的看板数是否等于board_limit”来决定是否继续翻页因此调大它可减少请求次数但需注意不要超过 Monday API 单次查询的看板数量上限。如何获取 api_token按连接器 README 的指引获取 API Token 的官方路径是访问 Monday 开发者文档中的 “Accessing API tokens” 章节developer.monday.com下/api-reference/docs/authentication#accessing-api-tokens。基本流程是登录你的 monday.com 账号进入账户管理员设置找到开发者/API 相关入口创建或复制一个 API Token仅对管理员可见且应妥善保管将该 Token 填入数据源配置的api_token字段。获取 Token 后你可以直接用它与 Monday GraphQL API 的https://api.monday.com/v2端点交互进行验证——这正是该连接器内部真实调用的 API 地址见 client.py 的base_url。连接器架构与调用链从源码结构可以梳理出该数据源的完整调用链入口类Monday(Source)init.py继承自mage_integrations.sources.base.Source在初始化时构造Client并通过load_data()根据stream.tap_stream_id从STREAMS注册表中实例化对应的数据流类。客户端Client继承自 mage_integrations/mage_integrations/sources/http/client.py 中的Client基类重写了base_url与get_headers()所有请求最终由基类make_request()发出POST JSON bodyGraphQL 查询以query字段提交。数据流基类BaseStream实现了通用的加载循环不断以client.request(methodpost, body{query: ..., variables: ...})拉取数据将parse_response()的结果分批 yield 出去再根据get_next_page_token()判断是否继续翻页直到没有下一页为止。值得一提的是基类make_request()带有utils.ratelimit(100, 60)限速装饰器即每 60 秒最多 100 次请求并默认设置 300 秒的请求超时同时通过 STATUS_CODE_EXCEPTION_MAPPING 将 400/401/403/404/405/409/429/500/503 等状态码映射为BadRequestError、AuthenticationError、RateLimitError等具体异常。也就是说配置的 Token 失效401或触发 Monday 限流429时Mage 都会抛出对应类型的可读异常便于在管道日志中快速定位问题。五大数据流Stream详解STREAMS注册表streams.py共注册了 5 个数据流每个数据流都有对应的 JSON Schema 文件与主键定义数据流主键复制键Schema 文件数据内容boardsid无schemas/boards.json看板及其内嵌的 items条目与 column_valuesworkspacesid无schemas/workspaces.json工作区信息name、kind、descriptiongroupsid无schemas/groups.json看板内的分组title、position、colorcolumnsid无schemas/columns.json看板内的列定义archived、width、type 等board_viewsid无schemas/board_views.json看板的视图name、type、settings_strboards唯一支持分页的顶层数据流BoardsStream是分页与父子关系的核心。它通过带page和board_limit变量的 GraphQL 查询拉取看板列表query ($page: Int!, $board_limit: Int!) { boards(limit: $board_limit, page: $page, order_by: created_at) { id, updated_at, name, description, state, workspace_id, items { id, name, state, created_at, updated_at, column_values { id, title, text, type, value, additional_info } } } }其分页逻辑为第一页从page 1开始若本页返回的记录数恰好等于board_limit则page加 1 继续请求否则视为已到末页、停止翻页。同时BoardsStream.get_child_context()会把每条看板记录的id作为子数据流的上下文board_id下发给groups、columns、board_views。另外注意post_process()会把看板与 items 的id从字符串转换为整数而 schemas/boards.json 也相应地将id声明为integer类型。workspaces从看板反查工作区WorkspacesStream的查询会遍历boards节点的workspace字段取出每个看板所属工作区的id/name/kind/description并在parse_response()中跳过workspace为null的记录即未归属任何工作区的看板。由于它依赖全局看板列表反查实际含义是“所有可访问看板对应的工作区去重集合”。groups / columns / board_views三个父子子数据流这三个数据流都声明了parent_stream_type BoardsStream与ignore_parent_replication_keys True即它们以boards为父流、按看板逐个查询各自的 GraphQL 查询通过boards(ids: $board_id)定位具体看板groups查询分组的title / position / id / colorpost_process()中把position转为浮点数并回填board_idcolumns查询列的archived / id / settings_str / title / type / width同样回填board_idboard_views查询视图的id / name / type / settings_str。这意味着只要配置了api_tokenboards流会自动发现所有可访问的看板并驱动三个子流完成全量看板元数据抽取无需手工为每个看板填写board_id配置board_id配置项在此处更多作为兜底/定向手段存在。Schema 与数据一致性每个数据流都在 schemas/ 下提供独立的 JSON Schema字段类型与实际查询结果严格对应。几个值得注意的类型设计boards.json中id、workspace_id为integerupdated_at声明为date-time格式字符串items为宽松对象数组additionalProperties: true兼容 Monday items 中动态变化的 column_valuesgroups.json中position为number与源码中float()转换一致board_id声明为numbercolumns.json与board_views.json的id为stringMonday 的列 ID 与视图 ID 本质上是字符串标识所有 Schema 均设置additionalProperties: false约束已定义字段防止无关字段进入目标表。主键方面5 个数据流均以id作为唯一主键见各流的primary_keys且均未设置复制键replication_key None因此这些数据流默认按“全量替换/追加”方式同步适合看板元数据这类低频变化的数据。在 Mage 中配置并使用 Monday 数据源新建数据集成管道在 Mage 项目中创建一个 Data Integration 类型的管道Source 选择Monday填写配置依次填入api_token必填、board_id可选用于限定看板、board_limit默认 25控制boards流每页拉取数量可参照 templates/config.json 的结构选择要同步的数据流勾选boards、workspaces、groups、columns、board_views中需要的流并选择目标Destination运行管道点击运行后可打开日志观察各流的加载情况每个流完成后会打印Finish loading data for stream StreamName日志见 streams.py。配置或运行时的常见问题排查401 AuthenticationErrorapi_token无效或权限不足重新在 monday.com 管理后台生成 Token429 RateLimitError请求过于频繁连接器已内置 60 秒 100 次的限速可适当调大board_limit减少分页请求次数boards 流不返回数据确认账号下有可访问的看板且 Token 具备对应工作区/看板的读取权限。小结Monday 数据源是 mage-ai 数据集成体系中典型的“GraphQL API 父子流”型连接器对外只需api_token一个强校验凭据配合board_limit控制boards流的分页规模即可自动发现看板并级联抽取groups、columns、board_views与workspaces数据。理解其 streams.py 中的分页判定与子流board_id下发机制能帮助你在调优同步性能与排查权限问题时事半功倍。赞分享数据工程数据编排ETL任务调度批处理流处理数据集成后端【免费下载链接】mage-ai Build, run, and manage data pipelines for integrating and transforming data.项目地址https://gitcode.com/gh_mirrors/ma/mage-ai点击查看免费下载相关推荐10个提升Python编程效率的技巧Ultimate-Python-Resource-Hub高手经验分享10个提升Python编程效率的技巧Ultimate Python Resource Hub高手经验分享 Ultimate Python Resource H数据工程数据编排ETL任务调度批处理流处理数据集成后端前端PearcleanermacOS应用彻底卸载的终极解决方案PearcleanermacOS应用彻底卸载的终极解决方案 你是否曾注意到在macOS上删除应用后磁盘空间并没有明显增加这并非错觉——大多数应用在卸载时数据工程数据编排ETL任务调度批处理流处理数据集成后端前端AMD量化模型生产部署终极指南容器化、监控与性能优化全流程AMD量化模型生产部署终极指南容器化、监控与性能优化全流程 在当今AI应用快速发展的时代 AMD量化模型 的生产部署已成为企业实现高效推理的关键技术。本文将数据工程数据编排ETL任务调度批处理流处理数据集成后端前端上一篇2025最新PHPWord教程10分钟上手Word文档自动化下一篇Noi浏览器批量提问1键同步13个AI站点的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考