Notion Pages API 实战:创建/更新数据库条目、图标封面定制与 in_trash 软删除归档工程指南

2026 年 11 月 20 日

一、从 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 或写入失败,核心变化集中在三点:

  1. 数据库建行必须指定 data_source_id 而非旧版 database_id:新版多源数据库模型中,一个容器数据库下可能挂接多个数据源表(详见 Data Sources API 迁移实战)。向数据库插入新记录时,parent 应使用 {"type": "data_source_id", "data_source_id": "..."}。
  2. 软删除与恢复字段由 archived 统一收口为 in_trash:调用 PATCH /v1/pages/{page_id} 传入 {"in_trash": true} 即可将页面(或数据库条目)移入废纸篓;传入 {"in_trash": false} 则将其从废纸篓无损还原。注意:Notion API 不提供“彻底永久删除”接口,物理清理需在界面废纸篓人工操作(详见 复制、删除和恢复内容指南)。
  3. 只读属性不可写入,且单页返回上限受 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 对齐、防误删与增量裁剪 #

要在十万级页面资产中实现零异常写入与安全生命周期归档,建议遵循以下四步规范(属性类型定义参阅 数据库属性全览):

  1. 写入前先拉取数据源 Schema 并剥离只读字段:调用 GET /v1/data_sources/{id} 获取真实列名与类型后,仅对 title、status、select、date、relation 等可写字段构造载荷;若目标字段为 status,注意选项名必须与库内预设完全一致(不存在的选项不会像 select 那样自动新建)。
  2. 用 in_trash: true 替代物理删除,保留 30 天容灾缓冲:对于超期未归档的临时草稿或作废工单,脚本先做状态标记并调用 PATCH /v1/pages/{page_id} 设置 in_trash: true。即便误判,管理员仍可在废纸篓或结合 页面历史版本 与 误删数据救援实战 秒级找回。
  3. 利用 icon 与 cover 外链规范实现视觉自动分级:可通过 {"type": "emoji", "emoji": "🚨"} 或 {"type": "external", "external": {"url": "https://..."}} 动态更新工单图标,在看板或列表视图中直观标示风险等级。
  4. 读取单页详情必带 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 投入大规模工单自动创建、状态同步或定时冷归档任务前,务必逐项落实以下五条上线检查规范:

  1. 新建页面附带正文超过 100 个 Block 时必须两段式写入:
    • POST /v1/pages 允许在 children 字段中随新页面一并写入正文块,但单次请求上限严格卡在 100 个 Block(且每块内单个 rich_text 节点不得超过 2000 字符)。对于长篇会议纪要或 AI 生成的项目方案,正确做法是先通过 POST /v1/pages 创建空页面并拿到返回的 page_id,再分批调用 PATCH /v1/blocks/{page_id}/children 每次追加不超过 100 个块。
  2. 区分 status 与 select 的写库容错差异,防止新枚举值报错:
    • 向 select 或 multi_select 属性写入尚未存在的新选项名称时,Notion 会自动在数据库 Schema 中新建该选项;但向 status(状态) 属性写入一个 Schema 里不存在的名称时,API 会直接报错 400 validation_error。凡涉及状态流转的外部同步,必须在脚本初始化时用 GET /v1/data_sources/{id} 校验目标状态名是否合法。
  3. 批量清理父页面时注意子页面级联进入废纸篓的副作用:
    • 通过 PATCH /v1/pages/{page_id} 将某个父页面或整张数据库设为 {"in_trash": true} 时,其内部所有子页面与子数据库条目会连带进入废纸篓状态。若下游还有其他库通过 Relation 关联了这些子页面,虽然关联记录不会彻底消失,但在常规界面和未过滤的同步查询中会被标记为已丢弃。因此脚本执行 in_trash: true 前,必须通过上述 Formula 2.0 门禁确认 被引用数 == 0。
  4. 避免在 cover 或 icon 中写入带短时效签名的对象存储 URL:
    • 通过 API 传入 external.url 设置封面图或自定义图标时,Notion 客户端直接加载该外链地址(不会像客户端拖拽上传那样转存至 Notion 托管存储)。如果业务系统把有效期仅 1 小时的 AWS S3 / 阿里云 OSS 预签名链接塞进 cover,次日全库卡片封面都会裂图。外部图标与封面务必使用持久公开 CDN 地址或上传接口返回的托管文件 ID。
  5. 批量建单务必在正文或唯一键属性保留外部流水号防重:
    • 网络超时或进程重启重试 POST /v1/pages 时,Notion 服务端不提供请求级 Idempotency-Key 去重头。生产级建单管道应在数据库增加一列 外部单号(Text),建单前先用 Data Sources Query 精确过滤 查询该单号是否已存在:存在则转走 PATCH 幂等更新,不存在才执行 POST 创建,彻底杜绝重复工单。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。