Notion API 2025-09-03 多源数据库(Data Sources API)迁移与企业级多表容器集成实战:从 database_id 到 data_source_id 解耦、Search 接口改造到 Formula 2.0 集成健康度巡检闭环

2026 年 11 月 19 日

一、为什么 Notion API 2025-09-03 是一次必须重视的架构级重构? #

在传统 Notion 数据模型中,一个数据库(Database)与一张数据表(Table Schema)是一一绑定的——开发者只要拿到 database_id,就可以直接查询行记录、读取属性结构或往里面新建页面。但随着 Notion 多源数据库(Multi-source Databases) 能力上线,同一个数据库视图容器中可以同时挂载多张不同属性结构的数据源表。

为支撑这一底层变化,Notion 官方在 Notion-Version: 2025-09-03 中正式推出了 Data Sources API:将“数据库容器(Database Container)”与“底层数据源表(Data Source)”彻底解耦。

对于正在运行生产级同步脚本、BI 数仓管道或 SaaS 集成服务的团队来说,这次升级存在一个非向后兼容(Breaking Change)的关键风险:如果集成仍停留在旧版 2022-06-28 请求头,一旦业务同事在某个 Notion 数据库中新增了第二个数据源,原有针对该 database_id 的查询、建页或 Schema 读取接口就会直接报错中断。

核心操作对比 旧版 API(2022-06-28 及更早) 新版 Data Sources API(2025-09-03) 架构迁移影响说明
查询行记录(Query) POST /v1/databases/{database_id}/query POST /v1/data_sources/{data_source_id}/query 必须先从数据库容器解析出目标 data_source_id 再发起查询
读取表结构(Schema) GET /v1/databases/{database_id} GET /v1/data_sources/{data_source_id}(字段结构)
GET /v1/databases/{database_id}(容器元信息与 data_sources 列表)
旧接口仅返回容器信息,列属性定义已下沉至 /v1/data_sources/
在库中创建新页面 parent: { "database_id": "..." } parent: { "type": "data_source_id", "data_source_id": "..." } 创建记录需显式声明写入哪一张底层数据源表
通过 API 创建数据库 在根 JSON 体直接传入 properties properties 需嵌套包裹在 initial_data_source 字段内 明确初始化数据库容器时同步创建首个数据源
全局搜索(Search API) filter: { property: "object", value: "database" } filter: { property: "object", value: "data_source" } Search 返回对象粒度改为 data_source,避免多表漏检
Webhooks 订阅事件 按旧版 Database 事件载荷推送 需在集成后台升级 Webhook 版本以适配数据源容器字段 需同步更新后端验签与 Payload 解析逻辑

若尚未完成速率限制容错与 Webhook 订阅基建搭建,建议先行阅读 Notion API 速率限制、分页与生产级容错架构 及 Notion API Webhooks 与自动化集成中枢实战。


二、企业级 API 集成资产与迁移治理三表数据库架构(SSOT) #

在中大型企业内部,往往同时运行着十几个财务对账、研发同步、CRM 线索写入和文档检索集成。如果靠人工记忆哪个脚本还在用 2022-06-28,极易在业务调整数据库结构时引发线上故障。建议在研发运维工作区建立以下三张通过 关系和汇总(Relations & Rollups) 联动的资产治理数据库,建模规范亦可对照 企业级数据库架构速查表:

数据库名称 核心属性(字段名与类型) 业务定位与幂等主键设计
DB_Notion_Integrations_Registry(集成服务主档) Integration_Key (Title,不可变英文标识,如 svc-crm-sync)、集成类型 (Select:Internal内部/Public OAuth)、当前API版本 (Select:2022-06-28/2025-09-03)、SDK版本 (Text,如 @notionhq/client@5.x)、负责人 (Person)、Webhook是否已升级 (Checkbox)、关联数据源 (Relation -> DB_Data_Sources_Catalog)、兼容性门禁状态 (Formula 2.0) 作为全司所有 Notion Integration 的单一真实数据源(SSOT),严禁在数据库内明文存放 ntn_ 或 secret_ 真实密钥
DB_Data_Sources_Catalog(多源数据库与 data_source_id 目录) DS_Key (Title,联合主键 {databaseId8}::{dataSourceId8})、所属容器ID (Text,脱敏或 UUID)、数据源ID (Text,data_source_id)、数据源别名 (Text)、接入集成 (Relation -> DB_Notion_Integrations_Registry)、所属容器源数量 (Number)、最近Schema校验时间 (Date) 精准映射每一个 database_id 下挂载了几个 data_source_id,提前暴露多源容器风险
DB_API_Migration_Checks(升级回归与报错巡检工单) Check_UID (Title,幂等键 MIG-{integrationKey}-{dayBucket})、所属集成 (Relation -> DB_Notion_Integrations_Registry)、异常类型 (Select:多源容器未适配/429限流告警/Webhook载荷不匹配/字段Schema漂移)、HTTP状态码 (Number)、处置状态 (Status:待排查/改造验证中/已上线关闭) 承接 CI/CD 契约校验或线上运行报错告警,形成闭环整改追踪

三、五步完成 2025-09-03 Data Sources API 平滑升级实操 #

结合 创建 Notion API 集成指南,遵循以下五步标准化流程可将现有生产服务无损迁移至新版接口规范:

1. 盘点现有集成与多源容器暴露面 #

首先在 Notion 开发者后台与业务部门确认:哪些核心数据库未来计划合并为多源视图(例如把各区域销售流水表挂载到同一个销售总览容器下)。所有调用这些数据库容器的脚本必须优先排入第一批迁移清单。

2. 实现 database_id -> data_source_id 自动发现与本地缓存 #

由于不再能假定 database_id 与表结构为 1:1 关系,服务启动或同步前需先调用 GET /v1/databases/{database_id} 获取响应中的 data_sources 数组。对于已知的单源数据库,可以直接取首个元素的 id 并缓存在内存或 Redis 中;对于多源容器,则需按数据源 name 精确匹配目标 data_source_id。

3. 统一升级请求头与分页/写入载荷 #

将全局 HTTP 客户端的 Notion-Version 请求头显式升级为 2025-09-03(若使用官方 TypeScript SDK @notionhq/client,请升级至支持 dataSources 命名空间的版本)。随后依次替换三处核心调用:

  • 行查询端点由 /v1/databases/{id}/query 切换为 /v1/data_sources/{data_source_id}/query;
  • 建页请求体中的 parent 由 {"database_id": "..."} 改为 {"type": "data_source_id", "data_source_id": "..."};
  • 全局搜索过滤条件由 value: "database" 改为 value: "data_source"。

4. 部署兼容 2025-09-03 的 Python 自动发现与幂等写入脚本 #

以下示例完整演示了在 Notion-Version: 2025-09-03 下,如何通过容器 ID 自动解析 data_source_id、执行带 429 指数退避的分页查询,并通过 data_source_id 幂等创建或更新页面记录:

import json
import os
import time
import urllib.error
import urllib.request

NOTION_TOKEN = os.environ["NOTION_TOKEN"]
CONTAINER_DB_ID = os.environ["NOTION_CONTAINER_DB_ID"]
NOTION_API_VERSION = "2025-09-03"


def notion_call(path: str, method: str = "GET", payload: dict | None = None) -> dict:
    url = f"https://api.notion.com/v1{path}"
    headers = {
        "Authorization": f"Bearer {NOTION_TOKEN}",
        "Notion-Version": NOTION_API_VERSION,
        "Content-Type": "application/json",
    }
    body = json.dumps(payload).encode("utf-8") if payload is not None else None
    for attempt in range(5):
        req = urllib.request.Request(url, data=body, headers=headers, method=method)
        try:
            with urllib.request.urlopen(req, timeout=20) as resp:
                return json.loads(resp.read().decode("utf-8"))
        except urllib.error.HTTPError as exc:
            if exc.code == 429:
                retry_after = float(exc.headers.get("Retry-After", str(2 ** attempt)))
                time.sleep(retry_after)
                continue
            err_body = exc.read().decode("utf-8", errors="ignore")
            raise RuntimeError(f"Notion API {exc.code} [{path}]: {err_body}") from exc
    raise RuntimeError(f"达到最大 429 重试次数: {path}")


def resolve_data_source_id(database_id: str, preferred_name: str | None = None) -> str:
    """从数据库容器元数据中发现并匹配对应的 data_source_id"""
    container = notion_call(f"/databases/{database_id}", "GET")
    sources = container.get("data_sources", [])
    if not sources:
        raise ValueError(f"数据库容器 {database_id} 未返回任何 data_sources")
    if preferred_name:
        for src in sources:
            if src.get("name") == preferred_name:
                return src["id"]
        raise ValueError(f"容器 {database_id} 中未找到名为 '{preferred_name}' 的数据源")
    return sources[0]["id"]


def query_all_rows_by_data_source(data_source_id: str, filter_obj: dict | None = None) -> list:
    rows = []
    cursor = None
    while True:
        payload = {"page_size": 100}
        if filter_obj:
            payload["filter"] = filter_obj
        if cursor:
            payload["start_cursor"] = cursor
        res = notion_call(f"/data_sources/{data_source_id}/query", "POST", payload)
        rows.extend(res.get("results", []))
        if not res.get("has_more"):
            break
        cursor = res.get("next_cursor")
        time.sleep(0.35)
    return rows


def upsert_record_by_data_source(data_source_id: str, key_prop: str, key_val: str, props: dict) -> str:
    matched = query_all_rows_by_data_source(
        data_source_id,
        {"property": key_prop, "title": {"equals": key_val}},
    )
    if matched:
        page_id = matched[0]["id"]
        notion_call(f"/pages/{page_id}", "PATCH", {"properties": props})
        return page_id
    created = notion_call(
        "/pages",
        "POST",
        {
            "parent": {"type": "data_source_id", "data_source_id": data_source_id},
            "properties": props,
        },
    )
    return created["id"]

5. 升级 Webhook 订阅版本与灰度验证 #

前往 Notion 集成控制台的 Webhooks 设置页,将订阅版本切换至适配多源数据结构的最新事件格式;并在预发布环境验证 page.created、database.schema_updated 等事件载荷是否能正确解析 parent.data_source_id。


四、Formula 2.0 实战:集成兼容性与多源断裂风险门禁公式 #

在 DB_Notion_Integrations_Registry 中添加名为 兼容性门禁状态 的 Formula 2.0 属性(更多语法参阅 Notion Formula 2.0 函数与公式速查字典)。该公式会自动检测该集成关联的所有数据库容器中,是否存在“拥有多个数据源(所属容器源数量 > 1)”但集成仍停留在旧版 2022-06-28 的高危隐患:

lets(
  apiVer, prop("当前API版本"),
  whReady, prop("Webhook是否已升级"),
  sources, prop("关联数据源"),
  multiSourceCount, sources.filter(current.prop("所属容器源数量") > 1).length(),
  staleSchemaCount, sources.filter(
    empty(current.prop("最近Schema校验时间")) ||
    dateBetween(now(), current.prop("最近Schema校验时间"), "days") > 14
  ).length(),

  ifs(
    apiVer != "2025-09-03" && multiSourceCount > 0,
      style("🛑 高危阻断 · 命中 " + multiSourceCount + " 个多源容器,旧版 API 即将失效", "red", "bold"),
    apiVer != "2025-09-03",
      style("🟠 待迁移 · 仍在使用旧版 2022-06-28,建议排期升级", "orange", "bold"),
    !whReady,
      style("🟡 API 已升级 · 需同步更新 Webhook 订阅格式", "yellow"),
    staleSchemaCount > 0,
      style("🔵 运行中 · 有 " + staleSchemaCount + " 个数据源超 14 天未巡检 Schema", "blue"),
    style("🟢 完全兼容 2025-09-03 · 多源与契约巡检正常", "green", "bold")
  )
)

五、Data Sources API 迁移常见报错与排查手册 #

迁移过程中最容易遇到容器 ID 与数据源 ID 混用、Search 过滤条件未改或建页 parent 报错,完整自救清单可同步对照 Notion 常见报错与故障诊断手册:

报错现象 / HTTP 状态 根因剖析 标准修复方案
multiple_data_sources 或 2022-06-28 查询突然报错 业务方在对应 Notion 数据库中新增了第二个数据源,旧版 API 无法识别多源容器 将集成请求头升级至 Notion-Version: 2025-09-03,先调用 GET /v1/databases/{id} 获取具体 data_source_id 再改调 /v1/data_sources/{id}/query
调用 /v1/pages 新建记录报 validation_error 请求头已是 2025-09-03,但请求体仍传 parent: { database_id: ... } 将 parent 修改为 {"type": "data_source_id", "data_source_id": "..."}
旧代码读取 GET /v1/databases/{id} 拿不到 properties 列定义 新版中 properties Schema 已从数据库容器剥离到具体数据源对象上 改用 GET /v1/data_sources/{data_source_id} 读取列字段定义,容器接口仅用于发现 data_sources 列表
调用 POST /v1/search 搜不到目标数据表 仍传入旧过滤条件 value: "database" 在 Notion-Version: 2025-09-03 下,将 Search 过滤器改为 {"property": "object", "value": "data_source"}

❓ 常见问题与答疑 (FAQ)

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

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