ToolJet 连接 Notion 数据源完整指南：从 API 接入到 Database、Page、Block、User 全量操作-平芜编程栈

ToolJet 连接 Notion 数据源完整指南：从 API 接入到 Database、Page、Block、User 全量操作

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

ToolJet 内置了 Notion 数据源插件，允许你在可视化画布中直接对 Notion 工作区的数据库、页面、块与用户执行增删改查操作，无需编写后端代码。本文以 ToolJet 3.0.0-LTS 版本配套文档为主线，结合仓库中 Notion 插件源码与操作清单配置，完整讲解从创建内部集成、建立数据源连接到四类资源共 16 种操作的配置方法与参数细节，帮助你快速构建基于 Notion 数据的内部工具、看板与自动化流程。

前置准备：创建 Notion 内部集成并获取 API Token

ToolJet 通过 Notion 官方 API 与你的工作区通信，因此接入的第一步是在 Notion 侧创建一个内部集成（Internal Integration）并获取 API Token：

打开你的 Notion 工作区设置，进入「Connections / 连接」或直接访问官方创建集成入口，按照 Notion 官方文档指引创建内部集成；
创建完成后，Notion 会生成一个形如secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx的 API Token（内部集成令牌以secret_开头）；
将 Token 复制保存，用于在 ToolJet 中建立数据源连接。

在仓库中，Notion 数据源插件通过官方@notionhq/clientSDK 与 Notion API 通信，Token 在运行时被注入客户端实例，见 plugins/packages/notion/lib/index.ts 中的getConnection方法：

const notion = new Client({ auth: token, });

同时，manifest.json 声明了数据源的唯一凭证字段token，并标记为encrypted: true，意味着 Token 会以加密形式存储于 ToolJet 的数据库中。

建立连接：添加 Notion 数据源

在 ToolJet 中建立 Notion 连接有两种入口：

点击查询面板上的+ Add new Data source按钮；
或从 ToolJet 仪表盘导航到数据源总览页。

在弹出的数据源列表中选中Notion，在Token输入框中粘贴上一步获取的 API Token 即可保存。

插件在testConnection中会执行一次notion.search({})来验证 Token 是否有效（见 index.ts），Token 无效时抛出Invalid token错误，因此保存失败时请检查 Token 的完整性与权限范围。

关键概念：如何从 URL 中提取 Database ID、View ID 与 Page ID

Notion 文档中的Database ID、View ID和Page ID都可以直接从工作区 URL 中读取，无需额外查询接口。以如下 URL 为例：

https://www.notion.so/workspace/XXX?v=YYY&p=ZZZ

其中：

参数	含义
`XXX`	Database ID（数据库 ID）
`YYY`	View ID（视图 ID）
`ZZZ`	Page ID（页面 ID）

此外，块（Block）的 ID 也有类似的获取方式：点击块的菜单图标，选择Copy link复制链接，粘贴到浏览器后得到形如下方的地址：

https://www.notion.so/Creating-Page-Sample-ee18b8779ae54f358b09221d6665ee15#7fcb3940a1264aadb2ad4ee9ffe11b0e

#号之后 32 位字符串7fcb3940a1264aadb2ad4ee9ffe11b0e即为该块的Block ID。

⚠️ 重要提示：在查询 Notion 之前，必须先将数据库（或页面）共享给你的集成。打开数据库视图，点击右上角的Share / 分享按钮，在弹窗中找到你的集成名称并选中它。否则 API 会因无权限而拒绝访问。

查询 Notion 的总体操作模型

Notion API 在 ToolJet 中按资源（Resource）与操作（Operation）两个维度组织查询。选中数据源新建查询后，先选择资源类型，再选择对应的操作：

Database（数据库）：检索、查询、创建、更新数据库；
Page（页面）：检索、创建、更新、归档页面，检索页面属性；
Block（块）：检索、追加子块、检索子块、更新、删除块；
User（用户）：检索单个用户、列出工作区用户。

这一「资源 + 操作」的调度模型在源码中清晰可见。入口 index.ts 根据queryOptions.resource分发到四个处理函数，每个处理函数内部再依据operation字符串调用@notionhq/client的对应方法：

switch (resource) { case 'database': result = await databaseOperations(notionClient, queryOptions, operation); break; case 'page': result = await pageOperations(notionClient, queryOptions, operation); break; // ... }

所有操作参数的 UI 表单均由 operations.json 声明驱动，下文各操作的参数说明均与该文件一一对应。

值得注意的底层细节：插件使用JSON5 解析用户输入的参数（见 operations.ts 中的returnObject），意味着 Filter、Properties、Children 等复杂结构字段支持带注释、宽松引号的 JSON5 语法，比严格 JSON 更宽容；而Limit会被parseInt转为整数；Start Cursor为空字符串时会被置为undefined以省略该参数。

查询 Notion 数据库（Database）

数据库资源支持四种操作，其中Query a database是日常使用频率最高的能力。

Retrieve a Database（检索数据库）

根据指定的Database ID获取数据库对象，包含其标题、图标、封面与属性结构定义。

必需参数：

Database ID：数据库 ID。

Query a Database（查询数据库）

获取数据库中包含的页面列表，并支持按过滤条件与排序规则筛选与排序，是读取数据库数据的核心操作。

必需参数：

Database ID：数据库 ID。

可选参数：

参数	说明	示例
Filter	过滤条件对象	`{or: [{ property: 'In stock', checkbox: { equals: true } }, ...]}`
Sort	排序数组	`[{"property": "Name", "direction": "ascending"}]`
Limit	返回的最大页数	`10`
Start Cursor	分页游标，用于获取下一页	上一页响应中的`next_cursor`

源码层面，Filter与Sort经 JSON5 解析后原样透传给 SDK 的databases.query，Limit映射为page_size，见 operations.ts 的query_database分支。

Create a Database（创建数据库）

在指定的父页面下创建数据库，并以子页面的形式存在，同时声明其属性结构。

必需参数：

Database ID：数据库 ID（作为目标位置的标识）；
Page ID：父页面 ID；
Properties：属性结构定义。

可选参数：

Title：数据库标题（富文本对象数组）；
Icon type：external（外链 URL）或emoji；
Icon value：图标值（外链 URL 或 emoji 字符）；
Cover type：external（外链 URL）；
Cover value：封面外链 URL。

Title 示例：

[ { "type": "text", "text": { "content": "Project Tasks Database", "link": null } } ]

Properties 示例（定义标题、日期与复选框三个属性）：

{ "Task Name": { "title": {} }, "Due Date": { "date": {} }, "Completed": { "checkbox": {} } }

源码中create_database会将父页面、标题、属性、封面与图标分别映射到 SDK 的databases.create对应字段；图标与封面经returnImgObject统一处理——只有external与emoji两种类型会被构建为合法的 API 结构，其余情况返回undefined表示不设置。

Update a Database（更新数据库）

按参数更新已有数据库的标题、属性结构、图标与封面。

必需参数：

Database ID：数据库 ID。

可选参数：

Title：新标题（富文本对象数组）；
Properties：需要新增或修改的属性定义；
Icon type/Icon value：图标类型与值；
Cover type/Cover value：封面类型与值。

Title 示例：

[ { "type": "text", "text": { "content": "Updated Tasks Database" } } ]

Properties 示例（添加一个下拉选择属性与一个人员属性）：

{ "Priority": { "select": { "options": [ { "name": "High", "color": "red" }, { "name": "Medium", "color": "yellow" }, { "name": "Low", "color": "green" } ] } }, "Assigned To": { "people": {} } }

查询 Notion 页面（Page）

页面资源支持五种操作，覆盖了页面的读取、创建、修改、归档与属性查询。

Retrieve a Page（检索页面）

根据Page ID获取页面对象，返回页面的属性、父级关系与 URL 等信息。

必需参数：

Page ID：页面 ID。

Create a Page（创建页面）

在指定数据库或已有页面下创建新页面。如果父级是数据库，Properties中的属性值必须符合父数据库的属性结构；如果父级是页面，则唯一合法的属性是title。

必需参数：

Parent Type：父级类型，可选Database（database_id）或Page（page_id）；
Page/Database ID：根据父级类型填写对应的 ID；
Properties：页面属性值。

可选参数：

Children (Blocks)：新页面的初始内容块数组；
Icon type/Icon value：图标类型与值；
Cover type/Cover value：封面类型与值。

Properties 示例：

{ "Title": { "title": [ { "type": "text", "text": { "content": "New Page Title" } } ] } }

源码中create_page会根据parent_type的值动态构造 parent 对象——当父级类型为database_id时只传database_id，为page_id时只传page_id（见 operations.ts）。

Update a Page（更新页面）

更新指定页面的属性值。未在Properties中设置的属性将保持不变，因此该操作可安全地用于局部更新。

必需参数：

Page ID：页面 ID；
Properties：需要更新的属性值。

可选参数：

Icon type/Icon value：图标类型与值；
Cover type/Cover value：封面类型与值。

Properties 示例（同时更新标题与状态属性）：

{ "Title": { "title": [ { "type": "text", "text": { "content": "Updated Page Title" } } ] }, "Status": { "select": { "name": "In Progress" } } }

Retrieve a Page Property Item（检索页面属性项）

根据Page ID与Property ID获取某个属性的取值。根据属性类型不同，返回结果可能是单个值，也可能是分页的属性值列表。

必需参数：

Page ID：页面 ID。

可选参数：

Property ID：属性 ID；
Limit：返回条数上限；
Start Cursor：分页游标。

Archive (Delete) a Page（归档 / 取消归档页面）

归档或取消归档指定页面，对应 Notion 的「移到废纸篓/恢复」语义。

必需参数：

Page ID：页面 ID；
Archive：布尔值，true归档，false取消归档。

源码中该操作复用pages.update，仅透传archived字段（见 operations.ts 的archive_page分支）。

查询 Notion 块（Block）

块是 Notion 内容结构的最小单元，支持五种操作。

Retrieve a Block（检索块）

根据Block ID获取块对象及其内容。

必需参数：

Block ID：块 ID（获取方式见上文「关键概念」小节）。

Append New Block Children（追加子块）

在指定的父块block_id下创建并追加新的子块。

必需参数：

Block ID：父块 ID；
Children：要追加的子块数组。

Children 示例（追加一个段落块）：

[ { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "Appended content" } } ] } } ]

Retrieve Block Children（检索子块）

获取指定块中包含的分页子块对象数组。

必需参数：

Block ID：块 ID。

可选参数：

Limit：返回条数上限；
Start Cursor：分页游标。

Update a Block（更新块）

根据块类型更新指定block_id的内容（如修改段落文本、切换列表样式等）。

必需参数：

Block ID：块 ID。

可选参数：

Properties：要更新的块属性对象；
Archive：true/false/None（不修改归档状态）。

Properties 示例：

{ "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "Updated block content" } } ] } }

源码中update_block会把properties对象展开后与archived一起合并进blocks.update调用（见 operations.ts），因此 Properties 应直接写块类型对应的内容结构。

Delete a Block（删除块）

删除（归档）指定的块。

必需参数：

Block ID：块 ID。

查询 Notion 用户（User）

用户资源支持两种操作，常用于获取任务负责人、构建人员信息类看板。

Retrieve a User From Current Workspace（检索工作区用户）

根据User ID获取指定用户对象。

必需参数：

User ID：用户 ID。

Retrieve List of Users of a Workspace（列出工作区用户）

返回当前工作区的分页用户列表。

可选参数：

Limit：返回条数上限；
Start Cursor：分页游标。

实战建议与常见问题

共享权限是第一步：绝大多数 401 权限错误都源于未将数据库/页面共享给集成，务必在查询前完成共享操作。
复杂字段使用 JSON5：Filter、Properties、Children、Sort 等字段由 JSON5 解析，可安全使用注释与宽松语法；但仍建议保持结构符合 Notion API 规范，避免静默失败。
分页处理：所有列表类操作（Query Database、List Users、Retrieve Block Children 等）都支持Limit+Start Cursor，可在 ToolJet 中结合查询结果中的next_cursor实现多页数据的循环拉取。
局部更新更安全：Update Page / Update Database 仅变更Properties中声明的字段，适合在表单提交场景中做增量保存。
更多 API 细节：Notion 官方提供了完整的 API Reference，字段类型、权限与速率限制细节可查阅 Notion 官方开发者文档（developers.notion.com/reference/intro）。