Notion API 集成
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/sundial-org-awesome-openclaw-skills-notion。
技能介绍
为什么要用 Notion API
很多团队把任务、文档和客户信息放在 Notion,但手工复制或只靠浏览器点选很难和脚本、CI、其他系统集成。Notion 官方 REST API 可以程序化读写页面、数据源(database)和块(blocks),适合把 Notion 当成可编排的后端知识库,而不是只能人工维护的 wiki。
技能能做什么
本技能围绕 Notion API(版本 2025-09-03) 组织常见调用方式,并强调当前版本里「数据库」在接口上改称 data source 后的路径与 ID 用法:
- 检索:搜索页面与数据源,拿到
database_id与data_source_id - 读取:按 ID 拉取页面元数据,以及页面下的块内容
- 写入:在数据源中新建页面、查询数据源、创建数据源、更新页面属性、向页面追加块
- 属性格式:列出 Title、Rich text、Select、Multi-select、Date、Checkbox、Number、URL、Email、Relation 等常见字段的 JSON 结构,便于构造请求体
使用前需在 Notion 集成后台 创建 Integration,保存以 ntn_ 或 secret_ 开头的 API Key,并把目标页面/数据库分享给该集成(「…」→ Connect to → 集成名称)。请求需带必需的 Notion-Version 头;建页时用 parent.database_id,查询数据源时用 POST /v1/data_sources/{data_source_id}/query。
边界与注意点
- 页面与数据库 ID 为 UUID,搜索返回的数据源对象类型为
data_source - API 不能设置数据库视图里的筛选条件,那是纯 UI 能力
- 平均速率大约 每秒 3 次请求,批量任务需要自行节流
- 在页面内嵌表格类数据源时,创建数据源可设
is_inline: true
使用场景
- CI 或 cron 任务需要根据 Notion 数据源查询结果,自动在某页面追加状态块或更新属性
- 要把外部工单系统里新单同步进 Notion 数据库行,并写入 Select、Date、Relation 等结构化字段
- Agent 根据用户描述搜索工作区里的页面与数据源,再读出指定页面的块内容做摘要或改写
- 运维脚本定期拉取项目数据库中的条目,合并变更后批量更新页面属性而非在 UI 里逐条编辑
适合人员
- 用 Notion 当项目台账、希望用脚本把 Git 发布记录写回数据库属性的工程师
- 负责客户成功、要把 CRM 导出字段映射到 Notion Relation/多选并自动建页的运营
- 构建带工具调用的 AI 助手、需要按 2025-09-03 区分 database_id 与 data_source_id 的集成开发者
- 维护内部知识库、想通过 API 新建子页面并插入富文本块而非手工粘贴的文档管理员