1. 为什么掌握 Notion API 是技术人员的超级杠杆？

Notion 不仅是一款强大的笔记和知识库软件，更是现代轻量级业务系统的无代码数据库。然而，当数据量庞大或需要与外部 CRM、财务系统、电商订单或自研后台打通时，手动复制粘贴不仅极其低效，更易造成数据不一致。

通过官方 Notion REST API，我们可以使用 Node.js、Python 或 Go 等任意编程语言，将 Notion 作为一个具备优雅前端 UI 的 Headless CMS 或低代码业务数据底座。

---

2. 授权认证与集成权限（Integration Setup）

在编写代码前，必须在 Notion 开发者平台完成集成授权：

┌────────────────────────────────────────────────────────┐
│              1. Notion Developers 开发者控制台           │
│   (https://www.notion.so/my-integrations)              │
│   创建新 Integration -> 获取 Internal Integration Secret │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│         2. 目标数据库/页面显式授权 (Crucial Step!)       │
│   打开数据库页面 -> 右上角 "..." -> "Connections"      │
│   -> 添加刚才创建的 Integration (否则返回 404 错误!)    │
└────────────────────────────────────────────────────────┘

常见报错提示

初学者调用 API 出现最多的错误是 object_not_found (404)。这是因为即使你的 Secret 密钥正确，若没有在具体数据库页面通过 Connections 手动添加该集成，Notion 安全沙箱也会彻底拒绝对该数据库的访问。

---

3. Node.js 生产实战：查询与写入多维数据库

官方为 JavaScript / TypeScript 开发者提供了成熟的 @notionhq/client SDK。

3.1 环境准备与安装

npm install @notionhq/client dotenv

3.2 自动化脚本：查询待处理任务并更新状态

import { Client } from '@notionhq/client';
import dotenv from 'dotenv';
dotenv.config();

const notion = new Client({ auth: process.env.NOTION_API_KEY });
const DATABASE_ID = process.env.NOTION_DATABASE_ID;

async function syncPendingTasks() {
  try {
    // 1. 过滤查询状态为 "待处理" 且优先级为 "High" 的卡片
    const response = await notion.databases.query({
      database_id: DATABASE_ID,
      filter: {
        and: [
          {
            property: 'Status',
            status: { equals: '待处理' }
          },
          {
            property: 'Priority',
            select: { equals: 'High' }
          }
        ]
      },
      sorts: [
        {
          property: 'CreatedAt',
          direction: 'ascending'
        }
      ]
    });

    console.log(`成功召回 ${response.results.length} 条待办任务`);

    // 2. 遍历处理并更新属性
    for (const page of response.results) {
      await notion.pages.update({
        page_id: page.id,
        properties: {
          Status: {
            status: { name: '同步中' }
          },
          SyncedAt: {
            date: { start: new Date().toISOString() }
          }
        }
      });
    }
  } catch (error) {
    console.error('Notion API 异常:', error);
  }
}

syncPendingTasks();

---

4. Python 生产实战：定时向 Notion 推送运营数据

Python 凭借丰富的数据科学与网络爬虫生态，非常适合做业务监控报表的自动化回填。

4.1 安装第三方或使用官方 notion-client

pip install notion-client requests

4.2 Python 自动化脚本：插入新客户记录

import os
from datetime import datetime
from notion_client import Client

notion = Client(auth=os.environ.get("NOTION_API_KEY"))
database_id = os.environ.get("NOTION_DATABASE_ID")

def insert_new_lead(customer_name, email, deal_amount):
    """向 Notion 客户线索库插入一条新销售记录"""
    new_page = {
        "parent": {"database_id": database_id},
        "properties": {
            "CustomerName": {
                "title": [{"text": {"content": customer_name}}]
            },
            "Email": {
                "email": email
            },
            "DealAmount": {
                "number": deal_amount
            },
            "LeadDate": {
                "date": {"start": datetime.now().strftime("%Y-%m-%d")}
            },
            "Status": {
                "status": {"name": "新线索待认领"}
            }
        }
    }
    
    response = notion.pages.create(**new_page)
    print(f"成功创建页面 ID: {response['id']}")
    return response['id']

if __name__ == "__main__":
    insert_new_lead("某某科技有限公司", "contact@example.com", 88000)

---

5. API 性能调优、分页与速率限制（Rate Limits）

当接入生产级数据流水线时，必须考虑接口稳定性和鲁棒性：

1. 处理速率限制（Rate Limiting）：
   • Notion API 官方默认限制为 平均每秒 3 次请求（3 requests/sec）；
   • 突发请求可能返回 HTTP 429 Too Many Requests；
   • 客户端必须实现指数退避重试（Exponential Backoff）机制；
2. 游标分页（Cursor Pagination）：
   • databases.query 默认单页最多返回 100 条记录；
   • 若数据库记录数大于 100，检查响应中的 has_more 字段，并将 next_cursor 作为下一次请求的 start_cursor 递归拉取；
3. 富文本字符边界保护：
   • 单个 Rich Text 块的 content 最大不能超过 2000 个字符；长篇文本入库前必须在代码中按 2000 字符切片。