Notion API 深度指南：赋能您的自动化与集成

您好！作为一名资深的全栈集成解决方案架构师，我非常理解您对 Notion API 深度和细节的渴望。Notion API 是一个强大而灵活的工具，它能将您的 Notion 工作区提升到前所未有的自动化和集成水平。本指南将带您深入探讨 Notion API 的各个方面，从核心概念到高级用法。

核心提示： Notion API 的强大之处在于其块级结构和灵活的属性系统。深入理解这两点是高效利用 API 的关键。

1. Notion API 架构概览与核心概念重温

Notion API 遵循 RESTful 架构，所有资源都通过唯一的 URL 标识。请求和响应都以 JSON 格式传输。理解其背后的模型是高效交互的基础。

1.1. 关键资源模型

Page (页面): Notion 中的核心内容容器，可以是一个独立的文档，也可以是数据库中的一行记录。每个 Page 都有一个唯一的 ID。
Block (块): 组成页面的基本内容单元。例如：标题、段落、列表、代码块、图片、嵌入内容等。每个 Block 也有其 ID。页面本质上是块的集合。
Database (数据库): 一个结构化的页面集合，其中每个页面都是数据库中的一个“条目”。数据库定义了其包含页面的属性（Schema）。
Property (属性): 数据库中用于组织和分类数据的列。Notion 支持多种属性类型，如 `title` (标题), `rich_text` (富文本), `number` (数字), `select` (单选), `multi_select` (多选), `date` (日期), `checkbox` (复选框), `url` (网址), `email` (邮箱), `phone_number` (电话), `people` (人员), `files` (文件), `formula` (公式), `relation` (关联), `rollup` (汇总), `created_time` (创建时间), `last_edited_time` (最后编辑时间) 等。
User (用户): Notion 工作区中的用户，可以是真实用户或您的集成（机器人）。

1.2. API 交互流程图

理解 API 交互的生命周期是构建稳健应用的基础。

graph TD UserApp[您的应用程序] -- 1. 发送 API 请求 (HTTP/HTTPS) --> NotionAPI[Notion API 服务器]; NotionAPI -- 2. 身份验证 & 授权 (Bearer Token) --> NotionInternal[Notion 内部服务]; NotionInternal -- 3. 执行操作 (数据读/写/更新) --> NotionDB[(Notion 数据存储)]; NotionInternal -- 4. 准备 JSON 响应 --> NotionAPI; NotionAPI -- 5. 返回 JSON 响应 --> UserApp; UserApp -- 6. 处理响应数据 --> DisplayUI[更新用户界面/执行后续逻辑];

2. 深入认证与授权

Notion API 提供两种主要的认证方式：

Internal Integration Token (内部集成令牌):
- 适用场景： 个人自动化、为特定工作区构建私有工具、公司内部集成。
- 获取方式： 在 Notion My Integrations 页面创建集成时直接生成。
- 安全性： 令牌本身就是凭证，需像密码一样严格保密，绝不能暴露在客户端代码中。
- 授权： 您必须手动将集成“邀请”到您希望其访问的特定页面或数据库。集成获得权限后，才能读写该页面及其子页面/数据库中的内容。
OAuth 2.0 (外部集成):
- 适用场景： 构建第三方应用，供其他 Notion 用户授权访问其工作区，例如 SaaS 产品集成 Notion。
- 流程概述：
  1. 您的应用引导用户到 Notion 授权页面。
  2. 用户授权后，Notion 将用户重定向回您的应用，并附带一个授权码。
  3. 您的应用使用授权码向 Notion API 交换一个访问令牌 (Access Token)。
  4. 您的应用使用这个访问令牌来代表用户向 Notion API 发送请求。
- 安全性： 访问令牌通常具有过期时间，并可被用户随时撤销。刷新令牌 (Refresh Token) 用于在访问令牌过期后获取新的访问令牌，无需用户重新授权。

安全警示： 无论使用哪种认证方式，都应确保您的 API 令牌或访问令牌存储在安全的服务器端，并通过 HTTPS 进行传输。切勿将这些敏感信息硬编码到前端代码中或通过不安全的通道传输。

3. 详细 API 端点与数据结构

Notion API 提供了丰富的端点来操作不同类型的资源。理解其请求和响应的 JSON 结构至关重要。

3.1. 统一请求头

所有 API 请求都必须包含以下 HTTP 头：

Header 名称	说明	示例值
`Authorization`	认证凭据，格式为 `Bearer YOUR_TOKEN`。	`Bearer secret_YOUR_TOKEN`
`Notion-Version`	指定您希望使用的 API 版本。Notion 会定期发布新版本，旧版本可能会废弃。	`2022-06-28` (推荐使用最新稳定版)
`Content-Type`	请求体的数据类型。对于 POST/PATCH 请求通常是 JSON。	`application/json`

3.2. 核心 API 端点与数据结构示例

3.2.1. 数据库操作

查询数据库 (POST /v1/databases/{database_id}/query):

这是最常用的端点之一，用于检索数据库中的页面。可以包含 `filter` (过滤), `sorts` (排序), `start_cursor` (分页游标), `page_size` (每页大小) 等。


// 请求体示例：查询状态为 "Done" 的任务
{
    "filter": {
        "property": "Status",
        "select": {
            "equals": "Done"
        }
    },
    "sorts": [
        {
            "property": "Last edited time",
            "direction": "descending"
        }
    ],
    "page_size": 100
}


// 响应体结构片段：
{
    "object": "list",
    "results": [
        {
            "object": "page",
            "id": "page_id_1",
            "created_time": "...",
            "last_edited_time": "...",
            "properties": {
                "Name": {
                    "id": "...",
                    "type": "title",
                    "title": [
                        {
                            "type": "text",
                            "text": { "content": "我的任务标题" },
                            "plain_text": "我的任务标题"
                        }
                    ]
                },
                "Status": {
                    "id": "...",
                    "type": "select",
                    "select": { "id": "...", "name": "Done", "color": "green" }
                },
                // ... 其他属性
            },
            // ...
        },
        // ...更多页面
    ],
    "next_cursor": "...", // 用于下一页请求
    "has_more": true,
    "type": "page_or_database",
    "page_or_database": {}
}

检索数据库 (GET /v1/databases/{database_id}):

获取数据库的元数据，包括其所有属性的定义。


// 响应体结构片段：
{
    "object": "database",
    "id": "database_id_1",
    "cover": null,
    "icon": { "type": "emoji", "emoji": "📋" },
    "created_time": "...",
    "last_edited_time": "...",
    "title": [
        {
            "type": "text",
            "text": { "content": "我的任务数据库" }
        }
    ],
    "properties": {
        "Name": { "id": "...", "type": "title", "title": {} },
        "Status": { "id": "...", "type": "select", "select": { "options": [...] } },
        "Tags": { "id": "...", "type": "multi_select", "multi_select": { "options": [...] } },
        // ... 其他属性定义
    },
    // ...
}

3.2.2. 页面操作

创建页面 (POST /v1/pages):

在数据库中创建新条目，或创建独立的顶级页面。


// 请求体示例：在数据库中创建新页面，并添加内容块
{
    "parent": { "database_id": "YOUR_DATABASE_ID" },
    "properties": {
        "任务名称": { // 注意这里是数据库中实际的属性名称
            "title": [
                { "text": { "content": "新的 API 任务条目" } }
            ]
        },
        "状态": {
            "select": { "name": "待办" }
        },
        "负责人": {
            "people": [
                { "id": "user_id_of_assigned_person" } // Notion 用户 ID 或集成 ID
            ]
        }
    },
    "children": [ // 可以在创建时直接添加子块
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    { "text": { "content": "这是任务的详细描述。" } }
                ]
            }
        },
        {
            "object": "block",
            "type": "to_do",
            "to_do": {
                "rich_text": [
                    { "text": { "content": "完成子任务 1" } }
                ],
                "checked": false
            }
        }
    ]
}

更新页面属性 (PATCH /v1/pages/{page_id}):

修改现有页面的属性值。


// 请求体示例：更新页面状态和添加标签
{
    "properties": {
        "Status": {
            "select": { "name": "已完成" }
        },
        "Tags": {
            "multi_select": [
                { "name": "API" },
                { "name": "自动化" }
            ]
        }
    }
}

3.2.3. 块操作 (Blocks)

Notion 的内容是基于块构建的。每个页面都是一系列块的集合。

检索块的子块 (GET /v1/blocks/{block_id}/children):

获取页面或任何容器块（如 Callout、Toggle list、Column）中的所有子块。这对于读取页面内容至关重要。


// 响应体结构片段：
{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block_id_1",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    { "type": "text", "text": { "content": "这是一个段落。" } }
                ],
                "color": "default"
            }
        },
        {
            "object": "block",
            "id": "block_id_2",
            "type": "heading_1",
            "heading_1": {
                "rich_text": [
                    { "type": "text", "text": { "content": "主标题" } }
                ]
            }
        },
        // ...更多块
    ],
    "next_cursor": null,
    "has_more": false
}

添加/更新块的子块 (PATCH /v1/blocks/{block_id}/children):

在现有页面或块的末尾追加新的子块，或更新现有子块的顺序。


// 请求体示例：在页面末尾添加一个代码块和一个图片块
{
    "children": [
        {
            "object": "block",
            "type": "code",
            "code": {
                "rich_text": [
                    { "text": { "content": "print('Hello Notion API!')" } }
                ],
                "language": "python"
            }
        },
        {
            "object": "block",
            "type": "image",
            "image": {
                "external": {
                    "url": "https://example.com/your-image.png"
                }
            }
        }
    ]
}

更新块 (PATCH /v1/blocks/{block_id}):
更新单个块的内容。例如，改变一个段落的文本，或更新一个 To-do 列表项的 `checked` 状态。
```
// 请求体示例：更新一个 To-do 块的完成状态
{
    "to_do": {
        "checked": true
    }
}
                
```
删除块 (DELETE /v1/blocks/{block_id}):
将块移动到垃圾桶。注意，删除块是不可逆的（无法通过 API 恢复）。

3.3. 富文本 (Rich Text) 对象

Notion 中几乎所有的文本内容（标题、段落、属性文本）都以富文本对象数组的形式表示。每个富文本对象可以包含不同的样式（粗体、斜体、下划线、颜色、链接）或提及（用户、页面、日期）。


[
    {
        "type": "text",
        "text": {
            "content": "这是一段",
            "link": null
        },
        "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
        },
        "plain_text": "这是一段",
        "href": null
    },
    {
        "type": "text",
        "text": {
            "content": "加粗斜体",
            "link": null
        },
        "annotations": {
            "bold": true,
            "italic": true,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "red"
        },
        "plain_text": "加粗斜体",
        "href": null
    },
    {
        "type": "mention",
        "mention": {
            "type": "page",
            "page": {
                "id": "another_page_id"
            }
        },
        "annotations": { /* ... */ },
        "plain_text": "@另一页",
        "href": "https://www.notion.so/..."
    }
]

4. 高级主题与最佳实践

4.1. 分页与迭代

Notion API 默认限制每页返回的条目数量 (通常是 100)。对于大型数据库，您需要使用 `next_cursor` 和 `has_more` 字段来迭代所有结果。


import requests

def query_database_all_pages(database_id, notion_token):
    url = f"https://api.notion.com/v1/databases/{database_id}/query"
    headers = {
        "Authorization": f"Bearer {notion_token}",
        "Notion-Version": "2022-06-28",
        "Content-Type": "application/json"
    }
    all_results = []
    has_more = True
    next_cursor = None

    while has_more:
        payload = {
            "page_size": 100
        }
        if next_cursor:
            payload["start_cursor"] = next_cursor

        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status() # 如果请求失败，抛出异常
        data = response.json()

        all_results.extend(data['results'])
        has_more = data['has_more']
        next_cursor = data['next_cursor']

    return all_results

# 使用示例
# pages = query_database_all_pages("YOUR_DATABASE_ID", "secret_YOUR_TOKEN")
# print(f"检索到 {len(pages)} 个页面。")

4.2. 错误处理与速率限制

Notion API 有严格的速率限制。当达到限制时，API 会返回 429 Too Many Requests 错误。您应该实现指数退避 (Exponential Backoff) 策略来处理这种情况。

常见的错误状态码：

400 Bad Request: 请求体格式错误或参数无效。
401 Unauthorized: 认证令牌无效或缺失。
403 Forbidden: 集成没有访问资源的权限。
404 Not Found: 资源 ID 不存在。
429 Too Many Requests: 速率限制。
500 Internal Server Error: Notion 服务器端错误。

4.3. Notion 官方 SDKs

Notion 官方提供了两种编程语言的 SDK，强烈推荐使用它们来简化开发：

JavaScript/TypeScript SDK: @notionhq/client
Python SDK: notion-client

这些 SDK 封装了 HTTP 请求细节、认证、版本管理以及复杂的 JSON 结构，提供了更友好的面向对象接口。


// 使用 Notion JavaScript SDK 查询数据库
const { Client } = require("@notionhq/client");

const notion = new Client({ auth: process.env.NOTION_TOKEN });

(async () => {
  const databaseId = process.env.NOTION_DATABASE_ID;
  const response = await notion.databases.query({
    database_id: databaseId,
    filter: {
      property: "Status",
      select: {
        equals: "待办",
      },
    },
  });
  console.log(response.results);
})();

5. 总结与展望

Notion API 提供了一个与您 Notion 工作区深度交互的强大接口。通过掌握其核心概念、API 端点和数据结构，您可以构建各种自动化工具和集成方案，极大地提升您的工作效率。

记住，实践是最好的学习方式。尝试从小功能开始，逐步扩展您的集成。Notion 官方文档和社区资源也将是您宝贵的伙伴。

祝您在 Notion API 的世界中探索愉快，并构建出令人惊叹的解决方案！如果您有任何更具体的集成场景或代码问题，请随时提出，我将继续为您提供专业支持。

目录导航