Notion

核心用法

Notion Skill 通过 Maton 网关代理访问官方 Notion API，实现对工作空间的完整操作能力。用户需先在 ctrl.maton.ai 完成 OAuth 授权建立连接，随后使用统一的 MATON_API_KEY 调用网关接口。核心功能覆盖：

• 搜索发现：全局搜索页面、数据库和数据源
• 数据操作：查询数据源（Data Source）、筛选排序记录、增删改页面属性
• 结构管理：创建数据库、更新数据源 schema、管理列定义
• 内容编辑：读取和追加块级内容（段落、标题、列表、代码块等）
• 用户管理：列出工作区成员、获取当前用户信息

API 版本锁定为 2025-09-03，该版本将传统数据库概念拆分为 Database（结构定义）和 Data Source（数据存储），查询前需通过 GET /databases/{id} 获取对应的 data_source_id。

显著优点

1. 托管 OAuth 简化集成：用户无需自行处理 OAuth 2.0 流程、Token 刷新和存储，Maton 集中管理连接生命周期
2. 统一网关入口：单一对接点 gateway.maton.ai 聚合认证和路由，降低客户端复杂度
3. 完整 API 覆盖：支持 Notion 核心读写能力，包括富文本块、嵌套属性和筛选语法
4. 多语言示例：提供可直接运行的 cURL、JavaScript、Python 代码片段

潜在局限

• 依赖第三方网关：所有流量经 Maton 代理，存在单点依赖风险；若网关不可用则完全中断
• 速率限制：每账户 10 req/sec，高频场景需自行实现退避重试
• 版本锁定：强制使用特定 API 版本，未来 Notion 官方升级可能存在兼容滞后
• 连接状态管理：OAuth 连接可能过期或失效，需额外监控 connection.status

适合人群

• 需要将 Notion 作为数据源集成到 AI Agent、自动化工作流或内部工具的技术团队
• 希望避免自建 OAuth 服务、快速原型验证的开发者
• 使用 Notion 管理项目、CRM、知识库，并寻求程序化操作的业务用户

常规风险

| 风险类型 | 说明 |

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

| 数据泄露 | OAuth 授权后 Skill 可访问用户可见的全部工作区内容，需最小权限原则 |

| 误操作 | `PATCH` 和 `DELETE` 操作直接修改生产数据，建议先测试再执行 |

| 服务可用性 | 网关或 Notion API 故障将导致功能中断，关键业务需设计降级方案 |

| Token 安全 | `MATON_API_KEY` 泄露将暴露所有已授权连接，需妥善保管 |

认证与授权

• 来源可信度：Maton 作为商业 API 网关服务商，具备基础可信度，但非 Notion 官方直属
• 安全等级：A 级——采用标准 OAuth 2.0 授权码流程，Token 由服务端托管，传输使用 HTTPS；需注意第三方网关的信任边界