MH notion

核心用法

Notion Skill 基于官方 REST API，提供对页面（Pages）、数据源（Databases，API 中称为 data sources）和块（Blocks）的完整 CRUD 操作能力。用户需先在 Notion 后台创建 Integration 并获取以 ntn_ 或 secret_ 开头的 API Key，通过环境变量 NOTION_API_KEY 注入。

关键流程：
1. 认证：所有请求需在 Header 携带 Authorization: Bearer {KEY} 及 Notion-Version: 2025-09-03
2. 授权：必须手动将目标页面/数据库与 Integration 共享（⚙️ → "Connect to"）
3. 操作：支持搜索、查询数据源、创建页面、更新属性、追加块内容等

2025-09-03 版本重大变更：

• 数据库概念拆分为 database_id（用于创建页面时的 parent）和 data_source_id（用于查询端点）
• 端点路径从 /databases 迁移至 /data_sources

显著优点

• 官方原生：Notion 官方维护，API 与产品功能同步更新
• 功能完备：覆盖从简单文本块到复杂关系型数据库的全部能力
• 结构化数据：支持 Select、Multi-select、Date、Relation 等丰富属性类型，适合构建轻量级 CMS 或任务系统
• 版本明确：强制 Notion-Version Header，避免破坏性更新导致故障

潜在缺点与局限性

• 权限粒度粗：Integration 需手动共享，无法基于规则自动授权；删除权限一旦授予即全局生效
• 速率限制：约 3 req/s 的平均限制，高频场景需引入队列或缓存
• UI 功能缺失：数据库视图筛选、公式计算结果等无法通过 API 设置
• ID 管理复杂：UUID 格式的 page/database/block ID 需人工维护，调试成本高

适合人群

• 个人/团队希望将 Notion 作为后端数据库，构建自动化工作流（如同步 GitHub Issues、日历事件）
• 开发者需要快速搭建内容管理原型，但无需传统数据库的复杂事务支持
• 已有 Notion 工作流，希望通过 API 实现批量数据迁移或报表生成

常规风险

| 风险类型 | 说明 |

|---------|------|

| **密钥泄露** | API Key 拥有 Integration 的全部权限，泄露后可被用于读取/篡改所有共享数据 |

| **数据误删** | API 支持硬删除操作，缺乏回收站保护机制 |

| **速率超限** | 突发流量易触发 429 错误，需实现指数退避重试 |

| **版本漂移** | 未来 API 版本升级可能导致当前调用模式废弃，需关注官方迁移指南 |