Notion

Notion 是一个办公协同插件，以插件能力的形式出现在指令树「扩展能力」中。安装或内置加载后，可把插件里的节点拖到工作流画布使用。

插件标识：rpa-plugin-notion
插件分类：办公协同插件
节点数量：12 个

先选使用方式

方式	怎么用	适合人群
可视化编排（推荐）	在「扩展能力」中找到 Notion，拖入需要的节点并填写参数	大多数用户，适合按表单配置插件能力
代码编排（执行指令 XML）	通过「执行指令（XML）」调用节点的 type 与参数	需要动态拼装、循环调用或批量处理的用户

什么时候用？

• Notion 业务节点 + 凭据连接：12 个原子节点覆盖 database 查询 / page CRUD / 归档 / 批量创建 / 正文 blocks 读写 / 全局搜索 / 本地 URL 解析。通过 Internal Integration Token 鉴权，自动注入 Notion-Version 协议头；properties / blocks 支持扁平 JSON 输入并自动 codec 成 Notion 原生结构；限频 3 req/s 由 client 层 token bucket 自动管理，用户无需手动控速。
• 需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

• 需要先配置连接：notion。
• 办公协同类能力需要确认文件、表格、空间或数据库的访问权限。
• 建议先运行连通性、查询或只读节点，确认权限和参数正确后再执行写入类节点。

连接配置

连接类型	名称	说明
notion	notion	Notion Internal Integration 凭据（用于业务节点 + HTTP 节点鉴权）

节点总览

节点名称	节点标识	说明
连通性测试	NotionPing	调 GET /users/me 验证 Notion Integration Token 可用且已开通访问权
获取数据库 schema	GetNotionDatabaseSchema	获取 Notion database 的字段定义（properties 列表 + 类型 + 选项）。常用于动态构造 properties JSON 时先看一眼字段名/类型
查询数据库记录	QueryNotionDatabase	按 filter / sorts 翻页查询 database 记录。自动 codec 字段值（rich_text → 字符串、select → 值、multi_select → 数组、date → 对象）
获取单条 page	GetNotionPage	按 pageId 取单条 page（含 properties），自动 codec
新建 Page / Record	CreateNotionPage	在 database 下新建 record，或在 page 下新建子 page。parentType=auto 时按 URL/properties 自动识别
更新 Page properties	UpdateNotionPage	局部更新 page 的 properties / icon / cover。只传要改的字段；归档/恢复请用 ArchiveNotionPage 节点
归档 / 恢复 Page	ArchiveNotionPage	归档（archived=true）或恢复（archived=false）一个 page。归档非永久删除——进 trash 30 天，可恢复
批量新建 Records	BatchCreateNotionPages	在同一 database 下批量创建多条 record。Notion 无官方批量接口，本节点串行调度 + 内部 token bucket 限流（3 req/s）。默认 fail-fast；continueOnError=true 时容忍单条失败
读取 Page 正文 blocks	GetNotionPageContent	拉取 page 的正文 block children（自动翻页）。自动 decode 把 rich_text 拼成 plain text 字符串平铺到顶层；raw 字段保留完整原始结构。不递归展开子 block（避免性能踩坑），需要深层时对子 blockId 再调一次本节点
追加 Blocks 到 Page	AppendNotionBlocks	在 page 末尾追加 blocks。支持字符串简写（默认 paragraph）/ { type, text } 简写 / Notion 原生 block 三种形态混用。超过 100 条自动按 100 分片串行 PATCH，由 token bucket 限速
搜索 Workspace	SearchNotionWorkspace	全局搜索 integration 已被 share 过的 page / database。Notion 安全模型：未 share 的对象搜索不到。可按对象类型过滤，按 last_edited_time 排序
解析 Notion URL / ID	ResolveNotionUrl	纯本地节点：解析 Notion URL 或 ID，统一规范化成标准 36-UUID。不调网络、不需要 connection。常用于 workflow 早期把用户粘贴的 URL 转成 id，后续节点直接用

节点参数与输出

连通性测试

• 节点标识： NotionPing
• 节点说明： 调 GET /users/me 验证 Notion Integration Token 可用且已开通访问权
• XML 示例：

<NotionPing connectionId="" outKey="pingResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-	在「设置 → 集成与连接」中配置的 Notion Integration
输出变量名	outKey	output	否	pingResult
失败时抛错	failOnError	boolean	否	true	true：调用失败抛 节点错误 中断流程；false：失败结果写入 outKey 后继续往下走（需配合 if 节点判断 ok 字段）

输出字段：

字段	类型	说明
pingResult	object	成功：{ ok:true, data:{ connected:true, bot?, workspace? }, statusCode, attempts, durationMs, requestId? }；失败：{ ok:false, error, code, category, hint? }

获取数据库 schema

• 节点标识： GetNotionDatabaseSchema
• 节点说明： 获取 Notion database 的字段定义（properties 列表 + 类型 + 选项）。常用于动态构造 properties JSON 时先看一眼字段名/类型
• XML 示例：

<GetNotionDatabaseSchema connectionId="" url="" outKey="databaseSchema" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Database URL	url	string	否	-	粘贴 Notion database 链接；与 databaseId 二选一
databaseId（替代 URL）	databaseId	string	否	-	32 位 hex 或 36 位 UUID 均可
输出变量名	outKey	output	否	databaseSchema
失败时抛错	failOnError	boolean	否	true	true：调用失败抛 节点错误 中断流程；false：失败结果写入 outKey 后继续往下走

输出字段：

字段	类型	说明
databaseSchema	object	{ ok:true, data:{ id, title, propertiesByName:{ name:{id,name,type,config?} }, propertiesById }, … }

查询数据库记录

• 节点标识： QueryNotionDatabase
• 节点说明： 按 filter / sorts 翻页查询 database 记录。自动 codec 字段值（rich_text → 字符串、select → 值、multi_select → 数组、date → 对象）
• XML 示例：

<QueryNotionDatabase connectionId="" url="" pageSize="100" outKey="records" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Database URL	url	string	否	-	URL 或 databaseId 二选一
databaseId	databaseId	string	否	-
过滤条件（JSON 对象）	filter	textarea	否	-	Notion filter DSL，例如 {“property”:“状态”,“select”:{“equals”:“待办”}}，或 {“and”:[…]}
排序（JSON 数组）	sorts	textarea	否	-	例如 [{“property”:“创建时间”,“direction”:“descending”}]
每页条数	pageSize	number	否	100	默认 100，最大 100（Notion API 限制）
自动翻页拉全部	autoPaginate	boolean	否	true	true 时自动翻页拉完匹配记录；false 时只取第一页
最多翻页数	maxPages	number	否	50	防御无限循环；默认 50，上限 500
记录数上限	maxRecords	number	否	-	命中即停止；0 = 不限制；上限 1,000,000
自动解码字段值	decodeValues	boolean	否	true	把 rich_text / select / date 等复杂结构转成扁平 JSON
保留原始 properties	includeRawProperties	boolean	否	-	true 时同时返回 Notion 原始 properties 结构（用于高级场景）
输出变量名	outKey	output	否	records
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
records	object	{ ok:true, data:{ records:[{id,url,properties,createdTime,lastEditedTime,archived,rawProperties?}], total, hasMore, nextCursor? } }

获取单条 page

• 节点标识： GetNotionPage
• 节点说明： 按 pageId 取单条 page（含 properties），自动 codec
• XML 示例：

<GetNotionPage connectionId="" url="" outKey="page" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Page URL	url	string	否	-	URL 或 pageId 二选一
pageId	pageId	string	否	-
自动解码字段值	decodeValues	boolean	否	true
保留原始 properties	includeRawProperties	boolean	否	-
输出变量名	outKey	output	否	page
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
page	object	{ ok:true, data:{ id, url, properties, createdTime, lastEditedTime, archived, parent, rawProperties? } }

新建 Page / Record

• 节点标识： CreateNotionPage
• 节点说明： 在 database 下新建 record，或在 page 下新建子 page。parentType=auto 时按 URL/properties 自动识别
• XML 示例：

<CreateNotionPage connectionId="" url="" properties="&#123;&#125;" outKey="page" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
父资源 URL	url	string	否	-	粘 Database URL = 建 record；粘 Page URL = 建 child page。parentType=auto 时按此区分
parentId（替代 URL）	parentId	string	否	-	32 位 hex 或 36 位 UUID 均可
父资源类型	parentType	select	否	auto	auto = 智能识别（有 properties JSON 就按 database，否则按 page）
字段值（JSON，仅 database parent 用）	properties	textarea	否	-	扁平 JSON：{ “标题”:“工单 #123”, “状态”:“待办”, “截止”:“2024-01-15”, “负责人”:[“user_uuid”] }；自动 codec
标题（仅 page parent 用）	title	string	否	-	新建 child page 时的标题；database parent 请用 properties.标题 字段
正文 blocks（JSON 数组，可选）	children	textarea	否	-	Notion block 数组，原样透传给 API。例如 [{“object”:“block”,“type”:“paragraph”,“paragraph”:{“rich_text”:[{“type”:“text”,“text”:{“content”:“hello”}}]}}]
图标 emoji（可选）	iconEmoji	string	否	-	📄
封面图 URL（可选）	coverUrl	string	否	-
跳过 codec	skipCodec	boolean	否	-	true 时直接透传 properties 给 Notion API（已自行准备好原生结构时使用）
严格 codec	strictCodec	boolean	否	-	true 时遇到字段元信息缺失或类型不匹配直接抛错；false 时降级为 warn
输出变量名	outKey	output	否	page
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
page	object	{ ok:true, data:{ id, url, createdTime, properties? } }

更新 Page properties

• 节点标识： UpdateNotionPage
• 节点说明： 局部更新 page 的 properties / icon / cover。只传要改的字段；归档/恢复请用 ArchiveNotionPage 节点
• XML 示例：

<UpdateNotionPage connectionId="" url="" properties="&#123;&#125;" outKey="page" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Page URL	url	string	否	-
pageId（替代 URL）	pageId	string	否	-
要更新的字段（JSON 对象）	properties	textarea	否	-	只传要改的字段；显式传 null 等于清空该字段。properties / iconEmoji / coverUrl 至少传一个
图标 emoji	iconEmoji	string	否	-	空串清空
封面图 URL	coverUrl	string	否	-	空串清空
跳过 codec	skipCodec	boolean	否	-
严格 codec	strictCodec	boolean	否	-
输出变量名	outKey	output	否	page
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
page	object	{ ok:true, data:{ id, url, lastEditedTime, properties? } }

归档 / 恢复 Page

• 节点标识： ArchiveNotionPage
• 节点说明： 归档（archived=true）或恢复（archived=false）一个 page。归档非永久删除——进 trash 30 天，可恢复
• XML 示例：

<ArchiveNotionPage connectionId="" url="" archived="true" outKey="archiveResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Page URL	url	string	否	-
pageId（替代 URL）	pageId	string	否	-
归档状态	archived	select	否	true
输出变量名	outKey	output	否	archiveResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
archiveResult	object	{ ok:true, data:{ id, archived, lastEditedTime } }

批量新建 Records

• 节点标识： BatchCreateNotionPages
• 节点说明： 在同一 database 下批量创建多条 record。Notion 无官方批量接口，本节点串行调度 + 内部 token bucket 限流（3 req/s）。默认 fail-fast；continueOnError=true 时容忍单条失败
• XML 示例：

<BatchCreateNotionPages connectionId="" url="" records="[]" outKey="records" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Database URL	url	string	否	-
databaseId（替代 URL）	databaseId	string	否	-
记录数组（JSON）	records	textarea	是	[]	每项是一份扁平 properties 对象，例如 [{“标题”:“a”},{“标题”:“b”,“日期”:“2024-01-15”}]
单条失败时继续	continueOnError	boolean	否	-	false（默认）：任一条失败立即停，hint 含已成功 IDs 便于去重重跑；true：跳过失败项继续后续
跳过 codec	skipCodec	boolean	否	-
严格 codec	strictCodec	boolean	否	-
输出变量名	outKey	output	否	records
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
records	object	成功：{ ok:true, data:{ records:[{id,url}], total } }；部分失败（continueOnError=true）：{ ok:true, data:{ records, total, failedCount, failedIndexes } }；fail-fast 失败：{ ok:false, error, hint 含已成功 IDs }

读取 Page 正文 blocks

• 节点标识： GetNotionPageContent
• 节点说明： 拉取 page 的正文 block children（自动翻页）。自动 decode 把 rich_text 拼成 plain text 字符串平铺到顶层；raw 字段保留完整原始结构。不递归展开子 block（避免性能踩坑），需要深层时对子 blockId 再调一次本节点
• XML 示例：

<GetNotionPageContent connectionId="" url="" outKey="blocks" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Page URL	url	string	否	-	URL 或 pageId 二选一；也可以传任意 blockId 拉子 block
pageId / blockId	pageId	string	否	-
每页条数	pageSize	number	否	100	默认 100，最大 100
自动翻页	autoPaginate	boolean	否	true
最多翻页数	maxPages	number	否	50	防御无限循环；默认 50，上限 500
自动 decode blocks	decodeBlocks	boolean	否	true	把 rich_text 拼成 plain text 字符串；保留 raw 字段供高级场景
输出变量名	outKey	output	否	blocks
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
blocks	object	{ ok:true, data:{ blocks:[{ id, type, text?, hasChildren, archived, createdTime, lastEditedTime, raw }], total, hasMore, nextCursor? } }

追加 Blocks 到 Page

• 节点标识： AppendNotionBlocks
• 节点说明： 在 page 末尾追加 blocks。支持字符串简写（默认 paragraph）/ { type, text } 简写 / Notion 原生 block 三种形态混用。超过 100 条自动按 100 分片串行 PATCH，由 token bucket 限速
• XML 示例：

<AppendNotionBlocks connectionId="" url="" blocks="[]" outKey="blocks" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
Page URL	url	string	否	-
pageId / blockId	pageId	string	否	-	可以是 page 也可以是任意 block，blocks 会作为该 block 的 children 追加
Blocks（JSON 数组）	blocks	textarea	是	[]	每项可以是：(1) 纯字符串 → paragraph；(2) { type, text } 简写（type=paragraph/heading_1/heading_2/heading_3/bulleted_list_item/numbered_list_item/quote/callout/code/to_do/divider）；(3) Notion 原生 block 对象（{object:‘block’, type, [type]:{…}}）
插入点 blockId（可选）	after	string	否	-	指定后插入到该 block 之后；空 = 追加到末尾。仅对首批生效
输出变量名	outKey	output	否	blocks
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
blocks	object	{ ok:true, data:{ blocks:[{id,type,…}], total, batches } }；失败时 hint 含已追加批次数（重跑前请确认去重）

搜索 Workspace

• 节点标识： SearchNotionWorkspace
• 节点说明： 全局搜索 integration 已被 share 过的 page / database。Notion 安全模型：未 share 的对象搜索不到。可按对象类型过滤，按 last_edited_time 排序
• XML 示例：

<SearchNotionWorkspace connectionId="" query="" outKey="searchResults" />

界面名称	代码属性名	类型	必填	默认值	说明
Notion 连接	connectionId	connection	是	-
搜索关键词	query	string	否	-	空 = 列出全部可访问对象
类型过滤	filterType	select	否	-
按修改时间排序	sortDirection	select	否	-
每页条数	pageSize	number	否	100	默认 100，最大 100
自动翻页	autoPaginate	boolean	否	true
最多翻页数	maxPages	number	否	10	默认 10，上限 100（搜索结果一般不需要太多）
自动解码	decodeResults	boolean	否	true	把 title 拼成字符串、id / url / archived / type 平铺到顶层
输出变量名	outKey	output	否	searchResults
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
searchResults	object	{ ok:true, data:{ results:[{ id, type:‘page’|‘database’, title, url, archived, createdTime, lastEditedTime, raw }], total, hasMore, nextCursor? } }

解析 Notion URL / ID

• 节点标识： ResolveNotionUrl
• 节点说明： 纯本地节点：解析 Notion URL 或 ID，统一规范化成标准 36-UUID。不调网络、不需要 connection。常用于 workflow 早期把用户粘贴的 URL 转成 id，后续节点直接用
• XML 示例：

<ResolveNotionUrl input="" outKey="notionIds" />

界面名称	代码属性名	类型	必填	默认值	说明
URL 或 ID	input	string	是	-	Notion URL（https://www.notion.so/…）或直接的 32hex / 36-UUID
输出变量名	outKey	output	否	notionIds
失败时抛错	failOnError	boolean	否	true	false 时解析失败也写入 outKey 并继续（{ ok:false, code:‘NOTION_URL_PARSE_ERROR’ }）

输出字段：

字段	类型	说明
notionIds	object	{ ok:true, data:{ id, viewId?, kind:‘page’|‘database’|‘block’|‘unknown’ } }；kind 是启发式判断，准确类型需调 API

成功标准

• 节点运行状态为成功。
• 输出变量中包含预期字段，且可被下游节点引用。
• 对外部系统有写入动作的节点，目标系统中的数据状态与配置一致。

失败排查

现象 / 报错	可能原因	处理建议
找不到插件分组	插件未安装、未加载或当前端不是桌面客户端	在「扩展能力」中刷新/重新扫描插件，必要时重启客户端。
连接或鉴权失败	连接配置缺失、令牌过期或权限不足	重新配置连接，确认账号具备对应资源权限。
查询结果为空	筛选条件过窄、目标资源为空或页面状态不正确	放宽条件，检查资源 ID、日期范围和页面登录态。
写入类操作失败	参数格式不符合平台要求或目标资源不可写	先用少量测试数据验证，再检查必填字段、ID 和权限。

相关说明

• 插件能力由桌面端扩展能力机制加载，和普通后端指令树不是同一数据源。
• 插件页按插件维度整理；每个节点的帮助入口会跳到所属插件页，页面内可查节点标识、参数和输出。