NotionAPI技能：用一句话让 AI 助手直接读写你的 Notion 页面与数据库
- 能力定位：这是一份围绕 Notion 官方 API 的「技能说明书+调用手册」，让 AI 助手按统一规则完成页面、数据库（新版称“数据源”）与内容块的创建、读取和更新。
- 关键门槛：只需准备一个 Notion 集成密钥（以
ntn_或secret_开头），并把它保存到本地配置路径，即可开始调用。 - 版本要点：技能固定使用
Notion-Version: 2025-09-03，该版本中数据库在接口层被称为“数据源”，并区分database_id与data_source_id。 - 典型收益：把“手动点选整理 Notion”变成“用一段描述驱动自动建库、批量写入、状态回写”，适合项目跟踪、内容归档、自动化日报等场景。
- 注意事项：接口平均速率约 3 次请求/秒，且数据库视图过滤器无法通过接口设置，只能在前端界面操作。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
基础信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | NotionAPI技能 |
| 技能英文名 | notion |
| 技能 ID | 13579 |
| 官方主页 | https://developers.notion.com |
| 主要环境变量 | NOTION_API_KEY |
它解决什么问题
Notion 本身是一个高度可定制的文档与数据库工具，但它的接口体系有几个“坑”：鉴权头必须带、版本头必须带、数据库在新版本中改叫“数据源”、创建页面用 database_id 而查询要用 data_source_id、各类属性的 JSON 结构各不相同。开发者或 AI 助手在没有明确指引时，往往会写出结构错误的请求体，或者因为缺少 Notion-Version 头而直接报错。
这个技能把这些要点整理成一套可执行的规范：环境准备、鉴权方式、常用接口、属性写法、版本差异全部写明，AI 助手拿到它之后，不必反复试错就能产出可用的请求。
“一键安装”的思路与步骤
这里的“安装”并不是下载一个安装包，而是把技能接入你的 AI 助手环境，并完成 Notion 侧的授权配置。整体分四步：
第一步，准备前提。你需要一个可用的 Notion 账号，并拥有目标页面或数据库的编辑权限。
第二步，创建集成并获取密钥。访问 https://notion.so/my-integrations 新建一个集成，复制生成的 API 密钥（以 ntn_ 或 secret_ 开头）。密钥属于敏感凭证，不要提交到代码仓库。
第三步，把密钥存到约定位置。技能约定的配置路径是 ~/.config/notion/api_key，执行：
mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key
如果你的运行环境使用环境变量方式注入凭证，则按技能元数据的要求设置 NOTION_API_KEY（具体注入方式以你所使用的 AI 助手平台的官方说明为准）。
第四步，把目标页面或数据库“连接”给集成。在 Notion 页面右上角点击“…”→“连接到”→选择你的集成名称。这一步最容易漏掉：没有分享给集成的页面，即使密钥正确也会返回无权限。
如何验证是否生效
用一次最小请求验证：从配置中读取密钥，调用搜索接口，看是否返回结果列表。若有返回，说明鉴权与授权都正常；若返回 401，检查密钥是否完整复制；若返回 404 或结果为空，多半是页面没有分享给集成。
至于这个技能的获取入口、是否需要付费、在具体平台上如何开启，请以你所使用平台的官方说明为准。
2. 该技能的主要功能和特点
- 页面读取与内容遍历：既能获取页面本身的属性，也能拉取页面的内容块列表，实现“读取整篇文档内容”。
- 数据库（数据源）全生命周期管理：支持创建数据源、定义属性结构、按条件查询、批量写入条目。
- 页面属性更新：可修改页面在数据库中的状态、日期、选择项等字段，适合做任务状态流转。
- 块级写入：支持向指定页面追加内容块，实现程序化写入正文。
- 属性类型全覆盖：标题、富文本、单选、多选、日期、复选框、数字、URL、电子邮件、关系等常见字段均有明确的 JSON 结构示例，避免“结构写错导致 400”。
- 版本差异有明确说明：直接点明
2025-09-03版本下“数据库 → 数据源”的命名变化，以及database_id与data_source_id的分工，这是很多手写脚本最容易翻车的地方。 - 面向 AI 助手的结构化设计：所有示例都是可直接复制运行的 curl 片段，AI 助手可以把变量替换后直接执行，减少中间翻译环节。
和普通工具比强在哪
普通的“Notion 自动化”往往依赖图形化流程编排，遇到复杂属性结构时需要一层层点选；而这份技能是“面向代码与 AI 的说明书”，你的诉求可以用自然语言表达，助手据此生成正确的请求结构，对非结构化需求（比如“把所有状态为待办且过期超过三天的任务标记为逾期”）更灵活。
3. 如何使用该技能？
第 1 步：明确请求的公共结构
所有请求都需要三个要素：鉴权头、版本头、内容类型头。技能给出的范式是：
NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X GET "https://api.notion.com/v1/..." \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"
提示：
Notion-Version头是必需的，缺失会直接报错。
第 2 步：先搜索，拿到 ID
不确定页面或数据库 ID 时，先用搜索接口按关键词检索：
curl -X POST "https://api.notion.com/v1/search" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{"query": "页面标题"}'
返回结果中，数据库会以 "object": "data_source" 的形式出现，并带出它的 data_source_id——这个 ID 后续查询时要用。
第 3 步：读取页面与页面内容
读取页面属性：
curl "https://api.notion.com/v1/pages/{页面_id}" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03"
读取页面正文块：
curl "https://api.notion.com/v1/blocks/{页面_id}/children" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03"
第 4 步：在数据源中创建一条记录
注意这里父级使用的是 database_id：
curl -X POST "https://api.notion.com/v1/pages" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"parent": {"database_id": "xxx"},
"properties": {
"名称": {"title": [{"text": {"content": "新项目"}}]},
"状态": {"select": {"name": "待办"}}
}
}'
第 5 步：查询数据源中的记录
注意这里用的是 data_source_id，并且支持过滤与排序：
curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"filter": {"property": "状态", "select": {"equals": "活跃"}},
"sorts": [{"property": "日期", "direction": "降序"}]
}'
第 6 步：从零创建一个数据源
curl -X POST "https://api.notion.com/v1/data_sources" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"parent": {"page_id": "xxx"},
"title": [{"text": {"content": "我的数据库"}}],
"properties": {
"名称": {"title": {}},
"状态": {"select": {"options": [{"name": "待办"}, {"name": "完成"}]}},
"日期": {"date": {}}
}
}'
如需嵌在页面中显示，创建时加上 is_inline: true。
第 7 步：更新属性与追加内容块
更新状态字段：
curl -X PATCH "https://api.notion.com/v1/pages/{页面_id}" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{"properties": {"状态": {"select": {"name": "完成"}}}}'
向页面追加一个段落块：
curl -X PATCH "https://api.notion.com/v1/blocks/{页面_id}/children" \
-H "Authorization: Bearer $NOTION_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"children": [
{"object": "block", "type": "段落", "paragraph": {"rich_text": [{"text": {"content": "你好"}}]}}
]
}'
第 8 步：按属性类型组装字段
写请求体时对照技能给出的类型格式，例如单选取 {"select": {"name": "选项"}}、多选取 {"multi_select": [{"name": "A"}, {"name": "B"}]}、日期取 {"date": {"start": "2024-01-15", "end": "2024-01-16"}}、关系取 {"relation": [{"id": "页面_id"}]}。类型不匹配是最常见的失败原因。
输出说明：接口统一返回 JSON。创建页面成功后会返回新页面的 id 与 url，可直接用于后续更新或分享；查询数据源会返回 results 数组；页面响应中的父级信息会同时显示 parent.data_source_id 与 parent.database_id。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 本技能（notion） | 面向开发者与 AI 助手的 Notion API 调用规范 | 页面/数据源/块的增删改查、属性结构示例、版本差异说明 | 需创建集成并配置密钥，熟悉命令行即可 | AI 驱动的批量整理、自动化脚本、状态流转 | 优势：结构清晰、示例可直接运行、AI 友好；不足：需要自行处理错误重试与限流 |
| 手写原生接口代码 | 原生 REST 调用 | 同上，完全自由 | 需自行查阅文档、试错 JSON 结构 | 深度定制、长期维护的项目 | 优势：可控性最强；不足：上手慢，版本升级需自行跟进 |
| 图形化自动化平台（如 Zapier、Make 等） | 无代码流程编排 | 触发器+动作的拖拽式集成 | 几乎零代码，但需按平台规则配置 | 简单同步、通知提醒 | 优势：上手快；不足：复杂属性映射受限，成本与额度以官方说明为准 |
| 开源自建自动化工具（如 n8n 等） | 自托管流程编排 | 节点式连接 Notion 与其他服务 | 需自行部署与维护 | 数据敏感、需私有化部署的团队 | 优势：数据自主可控；不足：运维成本高，节点行为需自行验证 |
说明：以上竞品的具体功能、定价与配额均以其官方说明为准，本技能不涉及对这些平台的评价。
对比结论：如果你的诉求是“让 AI 助手按自然语言指令直接操作 Notion”，本技能的性价比最高；如果是稳定的定时同步且团队没有工程能力，图形化平台更省心。
5. 该技能的典型应用场景与实际体验情况
场景一：项目负责人的周会前自动汇总
痛点：每周例会前要手动翻遍多个项目库，统计“进行中”“待办”的条目，重复劳动且容易漏。
使用方式：让助手先搜索定位到项目数据源，拿到 data_source_id 后按状态字段过滤，再用日期字段倒序排列，输出一份待办清单，并把结果追加到周会页面。
实际体验：查询接口的过滤与排序逻辑直观，助手只需知道字段名就能组装请求。注意：如果字段名是中文，务必与库中属性名完全一致，否则过滤不生效且不报错，只是返回为空。
场景二：内容运营的选题批量入库
痛点：选题散落在聊天记录和文档里，逐条手动录入 Notion 数据库耗时。
使用方式：让助手调用创建页面接口，按标题、状态、日期三类属性批量写入，状态默认给“待办”。
实际体验：属性类型的格式一旦对齐，批量写入非常顺畅。注意：接口平均速率约 3 次请求/秒，批量写入时需要分批并留出间隔，否则会触发限流。
场景三：工程师搭建任务自动归档
痛点：已完成任务长期堆积在同一个库里，需要定期归档到另一个数据源。
使用方式：先查询已完成条目，再在归档数据源中创建对应记录，最后把原条目状态改为“已归档”。
实际体验：跨库操作需要同时持有两个 ID，容易混淆 database_id 与 data_source_id。注意：创建页面时用 database_id，查询时用 data_source_id，这是新版本最容易出错的地方。
场景四：AI 助手的知识库写回
痛点：和 AI 对话产出的结论没有被沉淀，下次还要重新推导。
使用方式：让助手把对话结论整理为块结构，追加到指定页面的子块中，形成可检索的知识库。
实际体验：块写入的 JSON 结构稍显冗长，但技能已给出范式，复制修改即可。注意：数据库视图的过滤器无法通过接口设置，只能在前端界面手动配置。
6. 该技能能为用户带来的价值
效率层面：把“打开页面—找到库—逐条点选新建—填写字段”的重复操作，压缩为一次自然语言描述加一次接口调用。对于需要批量处理几十上百条记录的场景，节省的时间是线性的。
门槛层面：Notion API 的真实门槛不在鉴权，而在属性 JSON 的结构设计和版本命名差异。技能把这些“隐性知识”显性化，让不熟悉接口细节的人也能一次写对请求体。
协作层面：统一的配置路径（~/.config/notion/api_key）和统一的版本头，使团队成员之间的脚本可以直接复用，减少“我这能跑你那不能跑”的环境问题。
长期价值：Notion 的接口会随版本演进（如数据库到数据源的命名变化），技能把版本差异单独列出，相当于给项目预留了升级说明，降低后续维护成本。
7. 常见问题 FAQ
Q1：怎么安装这个技能？需要写代码吗？
不需要写复杂代码。安装本质是两步：一是在 https://notion.so/my-integrations 创建集成并拿到密钥；二是把密钥写入 ~/.config/notion/api_key，或按平台要求设置 NOTION_API_KEY 环境变量。之后在 AI 助手中启用该技能即可。具体启用入口以你所用平台的官方说明为准。
Q2：密钥配置正确，为什么还是读不到页面？
十有八九是漏了授权这一步。需要在该页面点击“…”→“连接到”→选择你的集成名称。未分享给集成的页面，即使密钥有效也会拿不到数据。
Q3：为什么创建页面能成功，查询却失败？
大概率是 ID 用错了。在 2025-09-03 版本中，创建页面时父级用 database_id，而查询要用 POST /v1/data_sources/{data_source_id}/query。两个 ID 不同，需要先通过搜索接口或 GET /v1/data_sources/{data_source_id} 获取。
Q4：这个技能收费吗？
技能本身是一份接口调用规范，不额外收费；但 Notion 官方接口的使用受其自身服务条款与配额约束，具体以 Notion 官方说明为准。
Q5：它和 Zapier 这类自动化平台怎么选？
如果需要复杂条件判断、希望由 AI 根据自然语言即时生成请求，选本技能；如果只是固定的“有新记录就发通知”这类简单流程，且团队没有工程能力，图形化平台更省事。两者也可以结合：用本技能做复杂逻辑，用平台做触发与通知。