Notion API的使用详解（实现database、page、block的新增与查询）

作者：hangge | 2024-12-17 08:35

Notion 不仅仅是一款云笔记软件，而是一个集文档编辑、任务管理、数据库、知识库、团队协作等多功能于一身的综合性工具。并且随着 Notion API 的发布，我们可以实现更多高级的自定义集成，例如自动更新任务、从外部数据源同步信息等。本文将通过样例演示如何使用 Notion API。

一、准备工作

1，API 接口说明

Notion API 遵循 RESTful 设计风格，所有涉及数据的内容，无论是请求体还是响应体，都以 JSON 的形式呈现，十分优雅。 Notion 当前支持的所有 API 接口可以在 Notion 开发者网站（点击访问）中查看。

（1）数据表 Database

获取指定数据表的字段等信息
过滤、排序后输出指定数据表的内容
查询所有允许操作的数据表

（2）页面 Page

获取指定页面中各字段的值
创建新页面
更新指定页面中各字段的值

（3）块 Block

列举指定页面中的所有块
在指定页面中创建新的块

（4）用户 User

查看指定用户的信息
查看工作区中所有用户的信息（包括机器人）

（5）搜索 Search

在有权限的范围内执行全局搜索

2，创建 Notion 机器人

我们在使用 Notion API 时，并不是以“账户”身份登录，来操作所有的数据表；而是通过创建一个个的机器人（称为 integration），每个机器人分别来完成不同的事务，并根据每个机器人所需涉及的数据表，分别对每个机器人进行访问授权。

（1）首先我们访问 Notion 机器人管理页面（点击访问），点击“New integration”按钮开始创建一个机器人：

（2）接着只需要填入机器人名字（比如我这里叫 test），然后点击“Submit”就可以快速创建一个机器人。

（3）提交后，系统会给出一个复杂的密钥，点击 Show 记录可以查看明文内容。这个需要记住，我们后面调用 API 接口时需要用到。密钥可以随时在机器人管理页面中查看。

3，邀请机器人

（1）我们需要在 Notion 中将机器人邀请至指定数据表（Database）中，机器人才有该数据表的操作权限。这里我创建一个名叫“API测试”的页面。

（2）接着我们为这个页面创建一个 database：

（3）为方便后面演示，我们给创建的数据表又增加了“URL”和“图标”两个属性字段：

（4）最后，我们点击右上角的“...”在显示的菜单中选择“Add connections”，然后找到我们创建的 test 机器人，点击它就可以将其邀请进来了。

二、接口调用样例

1，请求头设置

（1）后面所有的请求都要设置请求头，具体内容如下：

"Authorization": "机器人密钥", 
"Notion-Version": "Notion 版本"

（2）比如我这里使用 Postman 进行接口调用测试，那么 Header 设置如下。

提示：其中 Notion 版本设置 2022-06-28 即可，如果后续官方发布新版本，可以更新对应版本号。

2，获取数据表信息

（1）要获取指定数据表信息，我们需要先找到该数据表的 id。打开我们前面创建的数据表页面，点击右上角的“Share”按钮，然后点击弹出框“Copy link”按钮。

（2）这时数据表链接就辅助到剪贴板中了，我们粘贴出来可以看到中间那一部分编码就是数据表的 id 了：

（3）我们使用 Get 请求方式调用如下接口，其中 url 尾部部分替换成我们的数据表 id：

https://api.notion.com/v1/databases/3373319ed396420bacd781e88cdba4b1

（4）即可获取到该数据表的信息：

{
    "object": "database",
    "id": "3373319e-d396-420b-acd7-81e38cdba4b1",
    "cover": null,
    "icon": null,
    "created_time": "2024-01-09T01:19:00.000Z",
    "created_by": {
        "object": "user",
        "id": "e994e7e3-a70b-478f-9c41-2da941dd3238"
    },
    "last_edited_by": {
        "object": "user",
        "id": "e994e7e3-a70b-478f-9c41-2da941dd3238"
    },
    "last_edited_time": "2024-01-09T02:08:00.000Z",
    "title": [
        {
            "type": "text",
            "text": {
                "content": "API 测试",
                "link": null
            },
            "annotations": {
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "code": false,
                "color": "default"
            },
            "plain_text": "API 测试",
            "href": null
        }
    ],
    "description": [],
    "is_inline": false,
    "properties": {
        "图片": {
            "id": "%3AikN",
            "name": "图片",
            "type": "files",
            "files": {}
        },
        "Tags": {
            "id": "UQ%5Ck",
            "name": "Tags",
            "type": "multi_select",
            "multi_select": {
                "options": []
            }
        },
        "URL": {
            "id": "wAWl",
            "name": "URL",
            "type": "url",
            "url": {}
        },
        "Name": {
            "id": "title",
            "name": "Name",
            "type": "title",
            "title": {}
        }
    },
    "parent": {
        "type": "workspace",
        "workspace": true
    },
    "url": "https://www.notion.so/3373319ed396420bacd781e38cdba4b1",
    "public_url": null,
    "archived": false,
    "developer_survey": "https://notionup.typeform.com/to/bllBsoI4?utm_source=postman",
    "request_id": "0403b98d-975b-445a-a663-427256c95ea7"
}

3，在指定数据表下添加新页面记录

（1）要新增一个页面记录的话需要使用 Post 请求方式调用如下接口：

https://api.notion.com/v1/pages

（2）请求消息体内容格式如下，注意 database_id 替换成我们数据表的 id：

{
    "parent": {
        "database_id": "3373319ed396420bacd781e38cdba4b1"
    },
    "properties": {
        "Name": {
            "title": [
                {
                    "type": "text",
                    "text": {
                        "content": "这是一篇测试文章"
                    }
                }
            ]
        },
        "Tags": {
            "multi_select": [
                {
                    "name": "测试"
                },
                {
                    "name": "技术"
                }
            ]
        },
        "URL": {
            "url": "https://www.hangge.com"
        },
        "图片": {
            "files": [
                {
                    "external": {
                        "url": "https://www.hangge.com/blog/images/logo.png"
                    },
                    "name": "hangge.com",
                    "type": "external"
                }
            ]
        }
    },
    "children": [
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "这个是文章里面的第一段内容."
                        }
                    }
                ]
            }
        },
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "第二段内容是一个链接",
                            "link": {
                                "type": "url",
                                "url": "https://twitter.com/NotionAPI"
                            }
                        }
                    }
                ]
            }
        },
        {
            "object": "block",
            "type": "image",
            "image": {
                "type": "external",
                "external": {
                    "url": "https://www.hangge.com/blog/images/logo.png"
                }
            }
        }
    ]
}

（3）执行完毕后，可以看到 Notion 这边已经出现了这条记录。

4，获取所有页面记录列表（搜索记录）

（1）使用 Post 请求方式调用如下接口可以获取所有的页面记录列表，如果需要添加查询条件可以在消息体中设置筛选条件：

https://api.notion.com/v1/search

（2）接口返回的数据如下：

5，获取指定页面的信息

（1）要获取指定页面信息，我们需要先找到该页面的 id。打开我们前面新增的页面，点击右上角的“Share”按钮，然后点击弹出框“Copy link”按钮。

（2）这时页面链接就辅助到剪贴板中了，我们粘贴出来可以看到中间那一部分编码就是页面的 id 了：

（3）我们使用 Get 请求方式调用如下接口，其中 url 尾部部分替换成我们的页面 id：

https://api.notion.com/v1/pages/1663661c0fdc4585916e78532277c946

（4）接口返回的数据如下：

6，获取指定页面的内容

（1）要获取指定页面的内容（即页面内部的 block 以及 block 内容），我们需要先找到该页面的 id。打开我们前面新增的页面，点击右上角的“Share”按钮，然后点击弹出框“Copy link”按钮。

（2）这时页面链接就辅助到剪贴板中了，我们粘贴出来可以看到中间那一部分编码就是页面的 id 了：

（3）我们使用 Get 请求方式调用如下接口，注意替换 url 中的页面 id 部分内容：

https://api.notion.com/v1/blocks/1663661c0fdc4585916e78532277c946/children

（4）返回的数据结构如下：

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "d8146fef-b36f-48ec-8339-912b3d517fa9",
            "parent": {
                "type": "page_id",
                "page_id": "1663661c-0fdc-4585-916e-78532277c946"
            },
            "created_time": "2024-01-09T02:17:00.000Z",
            "last_edited_time": "2024-01-09T02:17:00.000Z",
            "created_by": {
                "object": "user",
                "id": "724293c3-bf16-44db-ba57-3552b31766c0"
            },
            "last_edited_by": {
                "object": "user",
                "id": "724293c3-bf16-44db-ba57-3552b31766c0"
            },
            "has_children": false,
            "archived": false,
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "这个是文章里面的第一段内容.",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "这个是文章里面的第一段内容.",
                        "href": null
                    }
                ],
                "color": "default"
            }
        },
        {
            "object": "block",
            "id": "76bcf2be-58a6-43aa-9d61-33968bb87fa9",
            "parent": {
                "type": "page_id",
                "page_id": "1663661c-0fdc-4585-916e-78532277c946"
            },
            "created_time": "2024-01-09T02:17:00.000Z",
            "last_edited_time": "2024-01-09T02:17:00.000Z",
            "created_by": {
                "object": "user",
                "id": "724293c3-bf16-44db-ba57-3552b31766c0"
            },
            "last_edited_by": {
                "object": "user",
                "id": "724293c3-bf16-44db-ba57-3552b31766c0"
            },
            "has_children": false,
            "archived": false,
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "第二段内容是一个链接",
                            "link": {
                                "url": "https://twitter.com/NotionAPI"
                            }
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "第二段内容是一个链接",
                        "href": "https://twitter.com/NotionAPI"
                    }
                ],
                "color": "default"
            }
        },
        {
            "object": "block",
            "id": "06a969e9-917c-4d52-9a21-0bc05ce49620",
            "parent": {
                "type": "page_id",
                "page_id": "1663661c-0fdc-4585-916e-78532277c946"
            },
            "created_time": "2024-01-09T02:17:00.000Z",
            "last_edited_time": "2024-01-09T02:17:00.000Z",
            "created_by": {
                "object": "user",
                "id": "724293c3-bf16-44db-ba57-3552b31766c0"
            },
            "last_edited_by": {
                "object": "user",
                "id": "724293c3-bf16-44db-ba57-3552b31766c0"
            },
            "has_children": false,
            "archived": false,
            "type": "image",
            "image": {
                "caption": [],
                "type": "external",
                "external": {
                    "url": "https://www.hangge.com/blog/images/logo.png"
                }
            }
        }
    ],
    "next_cursor": null,
    "has_more": false,
    "type": "block",
    "block": {},
    "developer_survey": "https://notionup.typeform.com/to/bllBsoI4?utm_source=postman",
    "request_id": "3b612674-3e30-4c6d-91f0-475096bdbf78"
}

7，获取指定 block 的内容

（1）要获取指定 block 的内容，我们需要先找到该 block 的 id。打开我们前面新增的页面，然后在目标 block 上点击右键，然后点击弹出菜单的“Copy link to block”菜单项。

（2）这时带有 block 编码信息的页面链接就复制到剪贴板中了，我们粘贴出来可以看到末尾那一部分编码就是 block 的 id 了：

（3）我们使用 Get 请求方式调用如下接口，注意替换 url 中的页 block id 部分内容：

https://api.notion.com/v1/blocks/76bcf2be58a643aa9d6133968bb87fa9