Notion Pages API 实战:创建/更新数据库条目、图标封面定制与 in_trash 软删除归档工程指南
一、从 archived 到 in_trash:Pages API 在 2025-09-03 版本的关键演进 #
在企业日常自动化中,无论是把客服表单写入项目库、动态修改工单状态、自动更换页面图标与封面,还是将过期草稿批量清理进废纸篓,底层都依赖 Notion Pages API(POST /v1/pages、GET /v1/pages/{page_id}、PATCH /v1/pages/{page_id})。然而升级到 Notion-Version: 2025-09-03 后,不少老脚本因为沿用旧版参数而频繁报错 400 或写入失败,核心变化集中在三点:
- 数据库建行必须指定
data_source_id而非旧版database_id:新版多源数据库模型中,一个容器数据库下可能挂接多个数据源表(详见 Data Sources API 迁移实战)。向数据库插入新记录时,parent应使用{"type": "data_source_id", "data_source_id": "..."}。 - 软删除与恢复字段由
archived统一收口为in_trash:调用PATCH /v1/pages/{page_id}传入{"in_trash": true}即可将页面(或数据库条目)移入废纸篓;传入{"in_trash": false}则将其从废纸篓无损还原。注意:Notion API 不提供“彻底永久删除”接口,物理清理需在界面废纸篓人工操作(详见 复制、删除和恢复内容指南)。 - 只读属性不可写入,且单页返回上限受
filter_properties控制:更新页面时,若 Payload 中不小心带入了Formula、Rollup、Created time或Unique ID等系统计算字段,接口会直接拒绝整批写入。
接口端点(2025-09-03) | 核心用途 | 关键请求结构与参数 | 高危踩坑与边界约束 |
|---|---|---|---|
POST /v1/pages | 在数据源或父页面下新建条目/子页 | parent(data_source_id 或 page_id)+ properties + 可选 children / icon / cover | children 单次最多附带 100 个 Block;普通子页仅允许传 title 属性 |
GET /v1/pages/{page_id} | 读取单页元数据与属性值 | Query 参数 ?filter_properties={prop_id} 按需裁剪列 | 不返回页面正文块,读正文需配合 Blocks API 递归读写 |
PATCH /v1/pages/{page_id} | 更新属性、图标封面或软删除恢复 | properties、icon、cover、in_trash(true/false) | 已在废纸篓中的页面不可直接改属性,须先传 in_trash: false 恢复 |
GET /v1/pages/{id}/properties/{pid} | 精准读取单个超长属性 | 支持 start_cursor 与 page_size 分页 | 当 relation 超过 25 条被截断时必须调用此接口补齐 |
二、Pages API 四步工程规范:Schema 对齐、防误删与增量裁剪 #
要在十万级页面资产中实现零异常写入与安全生命周期归档,建议遵循以下四步规范(属性类型定义参阅 数据库属性全览):
- 写入前先拉取数据源 Schema 并剥离只读字段:调用
GET /v1/data_sources/{id}获取真实列名与类型后,仅对title、status、select、date、relation等可写字段构造载荷;若目标字段为status,注意选项名必须与库内预设完全一致(不存在的选项不会像select那样自动新建)。 - 用
in_trash: true替代物理删除,保留 30 天容灾缓冲:对于超期未归档的临时草稿或作废工单,脚本先做状态标记并调用PATCH /v1/pages/{page_id}设置in_trash: true。即便误判,管理员仍可在废纸篓或结合 页面历史版本 与 误删数据救援实战 秒级找回。 - 利用
icon与cover外链规范实现视觉自动分级:可通过{"type": "emoji", "emoji": "🚨"}或{"type": "external", "external": {"url": "https://..."}}动态更新工单图标,在看板或列表视图中直观标示风险等级。 - 读取单页详情必带
filter_properties:当仅需核验某条记录的状态与in_trash标识时,在GET /v1/pages/{page_id}后追加?filter_properties=prop_id(Query检索优化参阅 Data Sources Query 实战)。
三、Python 实战:新建数据源条目与安全软删除归档脚本 #
以下脚本演示在 Notion-Version: 2025-09-03 下,向指定数据源创建带图标的任务条目,以及根据状态安全执行 in_trash 软删除或恢复:
import os
import time
from typing import Any
import httpx
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
DATA_SOURCE_ID = os.environ["NOTION_DATA_SOURCE_ID"]
HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2025-09-03",
"Content-Type": "application/json",
}
def call_notion(client: httpx.Client, method: str, url: str, **kwargs: Any) -> dict[str, Any]:
for attempt in range(5):
resp = client.request(method, url, headers=HEADERS, timeout=20.0, **kwargs)
if resp.status_code == 429:
time.sleep(float(resp.headers.get("Retry-After", 2 ** attempt)) + 0.25)
continue
resp.raise_for_status()
return resp.json()
raise RuntimeError(f"Pages API 请求失败: {method} {url}")
def create_task_page(client: httpx.Client, title: str, priority: str, due_iso: str) -> dict[str, Any]:
"""在 2025-09-03 数据源下新建页面并挂载 Emoji 图标"""
payload = {
"parent": {"type": "data_source_id", "data_source_id": DATA_SOURCE_ID},
"icon": {"type": "emoji", "emoji": "📌"},
"properties": {
"任务名称": {"title": [{"text": {"content": title}}]},
"优先级": {"select": {"name": priority}},
"截止日期": {"date": {"start": due_iso}},
},
}
return call_notion(client, "POST", "https://api.notion.com/v1/pages", json=payload)
def set_page_trash_state(client: httpx.Client, page_id: str, move_to_trash: bool) -> dict[str, Any]:
"""使用 in_trash 软删除或从废纸篓恢复页面"""
return call_notion(
client,
"PATCH",
f"https://api.notion.com/v1/pages/{page_id}",
json={"in_trash": move_to_trash},
)
四、Formula 2.0 实战:页面过期软删除与归档门禁闭环 #
为了防止自动化脚本把仍在引用的核心项目误丢进废纸篓,建议在《资产生命周期台账》中配置 状态(Status)、最后更新(Last edited time)、被引用数(Rollup/Number)与 核心保护(Checkbox)列,并建立如下 归档清理门禁 Formula 2.0 属性(公式调试规范参见 Formula 工程治理实战 与 Formula 2.0 速查手册):
lets(
protected, prop("核心保护"),
refCount, prop("被引用数"),
status, format(prop("状态")),
idleDays, dateBetween(now(), prop("最后更新"), "days"),
ifs(
protected,
style("🔒 核心锁定 · 禁止脚本归档", "blue", "bold"),
refCount > 0 && status == "拟作废",
style("⛔ 拦截清理:仍被 " + format(refCount) + " 条上游记录引用", "red", "bold", "red_background"),
status == "拟作废" && idleDays >= 30,
style("🗑️ 满足安全条件:可执行 in_trash 软删除", "orange", "bold", "yellow_background"),
idleDays >= 90,
style("🟡 沉睡超 " + format(idleDays) + " 天 · 待人工复核", "orange"),
style("🟢 活跃受控 · 无需清理", "green")
)
)
若接口返回
400 validation_error、404 object_not_found或页面无法更新属性,请结合 Notion 常见报错与故障诊断手册 与 数据库架构选型速查 核对页面授权、数据源 ID 与in_trash状态。
五、生产环境高频踩坑清单与上线前核验要点 #
在将 Pages API 投入大规模工单自动创建、状态同步或定时冷归档任务前,务必逐项落实以下五条上线检查规范:
- 新建页面附带正文超过 100 个 Block 时必须两段式写入:
POST /v1/pages允许在children字段中随新页面一并写入正文块,但单次请求上限严格卡在 100 个 Block(且每块内单个rich_text节点不得超过 2000 字符)。对于长篇会议纪要或 AI 生成的项目方案,正确做法是先通过POST /v1/pages创建空页面并拿到返回的page_id,再分批调用PATCH /v1/blocks/{page_id}/children每次追加不超过 100 个块。
- 区分
status与select的写库容错差异,防止新枚举值报错:- 向
select或multi_select属性写入尚未存在的新选项名称时,Notion 会自动在数据库 Schema 中新建该选项;但向status(状态) 属性写入一个 Schema 里不存在的名称时,API 会直接报错400 validation_error。凡涉及状态流转的外部同步,必须在脚本初始化时用GET /v1/data_sources/{id}校验目标状态名是否合法。
- 向
- 批量清理父页面时注意子页面级联进入废纸篓的副作用:
- 通过
PATCH /v1/pages/{page_id}将某个父页面或整张数据库设为{"in_trash": true}时,其内部所有子页面与子数据库条目会连带进入废纸篓状态。若下游还有其他库通过Relation关联了这些子页面,虽然关联记录不会彻底消失,但在常规界面和未过滤的同步查询中会被标记为已丢弃。因此脚本执行in_trash: true前,必须通过上述 Formula 2.0 门禁确认被引用数 == 0。
- 通过
- 避免在
cover或icon中写入带短时效签名的对象存储 URL:- 通过 API 传入
external.url设置封面图或自定义图标时,Notion 客户端直接加载该外链地址(不会像客户端拖拽上传那样转存至 Notion 托管存储)。如果业务系统把有效期仅 1 小时的 AWS S3 / 阿里云 OSS 预签名链接塞进cover,次日全库卡片封面都会裂图。外部图标与封面务必使用持久公开 CDN 地址或上传接口返回的托管文件 ID。
- 通过 API 传入
- 批量建单务必在正文或唯一键属性保留外部流水号防重:
- 网络超时或进程重启重试
POST /v1/pages时,Notion 服务端不提供请求级Idempotency-Key去重头。生产级建单管道应在数据库增加一列外部单号(Text),建单前先用 Data Sources Query 精确过滤 查询该单号是否已存在:存在则转走PATCH幂等更新,不存在才执行POST创建,彻底杜绝重复工单。
- 网络超时或进程重启重试
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。