# Notion API集成技巧掌握用于工作区自动化的 Notion API，包括数据库、页面、块、查询/过滤语法和集成模式。该技能涵盖了用于构建强大的 Notion 集成的官方 REST API 和 Python SDK。 ## 何时使用此技能 ### 在以下情况下使用 Notion API： * 自动化数据库输入和更新 * 从概念数据构建自定义仪表板 * 在Notion和外部系统之间同步数据 * 从模板以编程方式创建页面 * 使用复杂的过滤器查询数据库 * 与其他生产力工具建立集成 * 从概念数据库生成报告 * 实施工作流程自动化 ### 不要在以下情况下使用 Notion API： * 需要实时同步（API有速率限制） * 构建聊天/消息功能（使用 Slack API） * 需要文件存储解决方案（使用专用存储） * 仅简单任务管理（使用Todoist API） * 需要离线优先的解决方案（使用 Obsidian） * 需要亚秒级响应时间 ## 先决条件 ### 创建集成 1. 访问 https://www.notion.so/my-integrations 2. 点击“新集成” 3.名称：“我的集成” 4. 选择工作空间 5. 设置功能（读/写内容等） 6.复制“内部集成令牌” ### 将集成连接到页面 1. 打开您要访问的Notion页面/数据库 2. 单击“...”菜单（右上角） 3. 单击“连接”>“连接到”> 您的集成 4.集成现在可以访问此页面和子页面 ### 环境设置 # 设置环境变量导出NOTION_API_KEY =“secret_xxxxxxxxxxxxxxxxxxxxx” # 验证连接卷曲-s“https://api.notion.com/v1/users/me”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”|杰克 ### Python SDK安装 # 安装官方Python客户端 pip install 概念客户端 # 或者用紫外线 uv pip 安装 notion-client # 额外的依赖项 pip install python-dotenv 请求 ### 验证设置从 notion_client 导入客户端导入操作系统概念 = Client(auth=os.environ["NOTION_API_KEY"]) # 测试连接 me = notion.users.me() print(f"连接为：{me['name']}") # 列出可访问的数据库数据库 = notion.search(filter={"property": "object", "value": "database"}) print(f"找到 {len(databases['results'])} 数据库") ## 核心能力 ### 1\.数据库操作 **列出和搜索数据库：** # 搜索数据库卷曲-s -X POST“https://api.notion.com/v1/search”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”\ -H“内容类型：application/json”\ -d'{ “过滤器”：{ “属性”：“对象”， “值”：“数据库” } }' | jq '.结果[] | {id：.id，标题：.title[0].plain_text}' # 获取数据库模式卷曲-s“https://api.notion.com/v1/databases/DATABASE_ID”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”| jq '.properties' **Python - 数据库操作：** 从 notion_client 导入客户端导入操作系统概念 = Client(auth=os.environ["NOTION_API_KEY"]) # 搜索数据库结果=概念.搜索( 过滤器={“属性”：“对象”，“值”：“数据库”} ）对于结果中的数据库[“结果”]： title = db["title"][0]["plain_text"] if db["title"] else "无标题" print(f"数据库: {title} (ID: {db['id']})") # 获取数据库详细信息数据库 = notion.databases.retrieve(database_id="your-database-id") print(f"属性：{list(database['properties'].keys())}") # 创建数据库 new_db = notion.databases.create( 父={"type": "page_id", "page_id": "父页面id"}, title=[{"type": "text", "text": {"content": "任务数据库"}}], 属性={ “姓名”：{“标题”：{}}， “状态”：{ “选择”：{ “选项”：[ {"name": "待办事项", "color": "灰色"}, {"name": "进行中", "color": "蓝色"}, {“名称”：“完成”，“颜色”：“绿色”} ] } }, “优先”：{ “选择”：{ “选项”：[ {"name": "高", "color": "红色"}, {"name": "中", "color": "黄色"}, {“名称”：“低”，“颜色”：“灰色”} ] } }, “截止日期”：{“日期”：{}}， “受让人”：{“人”：{}}， "标签": {"multi_select": {"选项": []}}, "已完成": {"复选框": {}}, “注释”：{“rich_text”：{}} } ） print(f"已创建数据库：{new_db['id']}") # 更新数据库概念.数据库.更新( database_id =“您的数据库ID”， title=[{"type": "text", "text": {"content": "更新的标题"}}], 属性={ “新属性”：{“rich_text”：{}} } ） ### 2\.查询数据库 **基本查询：** # 查询所有项目卷曲-s -X POST“https://api.notion.com/v1/databases/DATABASE_ID/query”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”\ -H“内容类型：application/json”\ -d '{}' | jq '.结果' # 带过滤器的查询卷曲-s -X POST“https://api.notion.com/v1/databases/DATABASE_ID/query”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”\ -H“内容类型：application/json”\ -d'{ “过滤器”：{ “财产”：“状态”， “选择”：{ “等于”：“进行中” } } }' | jq '.结果' # 排序查询卷曲-s -X POST“https://api.notion.com/v1/databases/DATABASE_ID/query”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”\ -H“内容类型：application/json”\ -d'{ “排序”：[ { "property": "到期日", “方向”：“上升” } ] }' | jq '.结果' **Python - 查询操作：** # 简单查询结果 = notion.databases.query(database_id="your-database-id") 对于结果中的页面[“结果”]：道具=页面[“属性”] name = props["Name"]["title"][0]["plain_text"] if props["Name"]["title"] else "Untitled" 打印（f“- {名称}”） # 带过滤器的查询结果= notion.databases.query( database_id =“您的数据库ID”，过滤器={ “财产”：“状态”， “选择”：{ “等于”：“进行中” } } ） # 使用多个过滤器（AND）进行查询结果= notion.databases.query( database_id =“您的数据库ID”，过滤器={ “和”：[ { “财产”：“状态”， “选择”：{“等于”：“进行中”} }, { "属性": "优先级", “选择”：{“等于”：“高”} } ] } ） # 使用 OR 过滤器进行查询结果= notion.databases.query( database_id =“您的数据库ID”，过滤器={ “或”：[ {"property": "状态", "select": {"equals": "待办事项"}}, {“属性”：“状态”，“选择”：{“等于”：“进行中”}} ] } ） # 排序查询结果= notion.databases.query( database_id =“您的数据库ID”，排序=[ {"property": "优先级", "direction": "升序"}, {“属性”：“到期日”，“方向”：“升序”} ] ） # 分页查询 def query_all_pages(database_id,filter=None): """查询所有带分页的页面""" 所有结果 = [] 有更多=真开始光标=无而 has_more：响应 = notion.databases.query( 数据库id=数据库id，过滤器=过滤器， start_cursor=start_cursor, 页大小=100 ） all_results.extend(响应[“结果”]) has_more = 响应[“has_more”] start_cursor = response.get("next_cursor") 返回所有结果 all_items = query_all_pages("您的数据库 ID") print(f"总项目：{len(all_items)}") ### 3\.过滤器语法参考 **文本过滤器：** # 文本属性过滤器 {“属性”：“名称”，“标题”：{“等于”：“完全匹配”}} {“属性”：“名称”，“标题”：{“does_not_equal”：“不是这个”}} {“属性”：“名称”，“标题”：{“包含”：“部分”}} {“属性”：“名称”，“标题”：{“does_not_contain”：“排除”}} {“属性”：“名称”，“标题”：{“starts_with”：“前缀”}} {“属性”：“名称”，“标题”：{“ends_with”：“后缀”}} {“属性”：“名称”，“标题”：{“is_empty”：True}} {“属性”：“名称”，“标题”：{“is_not_empty”：True}} # 富文本属性 {“属性”：“注释”，“rich_text”：{“包含”：“关键字”}} **数字过滤器：** {“属性”：“金额”，“数量”：{“等于”：100}} {“属性”：“金额”，“数量”：{“does_not_equal”：0}} {"property": "金额", "number": {"greater_than": 50}} {“财产”：“金额”，“数量”：{“小于”：100}} {"property": "金额", "number": {"greater_than_or_equal_to": 10}} {“财产”：“金额”，“数量”：{“小于或等于”：99}} {"property": "金额", "number": {"is_empty": True}} {"property": "金额", "number": {"is_not_empty": True}} **日期过滤器：** {"property": "截止日期", "date": {"equals": "2025-01-17"}} {"property": "截止日期", "date": {"before": "2025-01-20"}} {"property": "截止日期", "date": {"after": "2025-01-10"}} {"property": "截止日期", "date": {"on_or_before": "2025-01-17"}} {"property": "截止日期", "date": {"on_or_after": "2025-01-01"}} {"property": "到期日", "date": {"is_empty": True}} {“property”：“截止日期”，“date”：{“is_not_empty”：True}} # 相对日期过滤器 {“property”：“截止日期”，“date”：{“past_week”：{}}} {“property”：“截止日期”，“date”：{“past_month”：{}}} {“property”：“截止日期”，“date”：{“past_year”：{}}} {“属性”：“截止日期”，“日期”：{“next_week”：{}}} {“属性”：“截止日期”，“日期”：{“next_month”：{}}} {“属性”：“到期日”，“日期”：{“next_year”：{}}} {“属性”：“截止日期”，“日期”：{“this_week”：{}}} **选择/多选过滤器：** # 选择 {“属性”：“状态”，“选择”：{“等于”：“完成”}} {“属性”：“状态”，“选择”：{“does_not_equal”：“完成”}} {“属性”：“状态”，“选择”：{“is_empty”：True}} {“属性”：“状态”，“选择”：{“is_not_empty”：True}} # 多选 {“属性”：“标签”，“multi_select”：{“包含”：“紧急”}} {“属性”：“标签”，“multi_select”：{“does_not_contain”：“已存档”}} {“属性”：“标签”，“multi_select”：{“is_empty”：True}} {“属性”：“标签”，“multi_select”：{“is_not_empty”：True}} **复选框过滤器：** {"property": "已完成", "checkbox": {"equals": True}} {"property": "已完成", "checkbox": {"equals": False}} **关系和汇总过滤器：** # 关系 {“属性”：“项目”，“关系”：{“包含”：“页面ID”}} {“属性”：“项目”，“关系”：{“does_not_contain”：“页面id”}} {“属性”：“项目”，“关系”：{“is_empty”：True}} {“属性”：“项目”，“关系”：{“is_not_empty”：True}} # 汇总（取决于汇总类型） {"property": "总任务", "rollup": {"number": {"greater_than": 5}}} {“属性”：“完成”，“汇总”：{“数字”：{“等于”：100}}} **复合过滤器：** # 和 { “和”：[ {"property": "状态", "select": {"equals": "进行中"}}, {"property": "优先级", "select": {"equals": "高"}}, {"property": "截止日期", "date": {"before": "2025-02-01"}} ] } # 或 { “或”：[ {"property": "状态", "select": {"equals": "待办事项"}}, {“属性”：“状态”，“选择”：{“等于”：“进行中”}} ] } # 嵌套（AND 与 OR） { “和”：[ { “或”：[ {"property": "优先级", "select": {"equals": "高"}}, {“属性”：“优先级”，“选择”：{“等于”：“中”}} ] }, {“属性”：“状态”，“选择”：{“does_not_equal”：“完成”}} ] } ### 4\.页面操作 **创建页面：** # 在数据库中创建页面卷曲-s -X POST“https://api.notion.com/v1/pages”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28”\ -H“内容类型：application/json”\ -d'{ “父”：{“database_id”：“DATABASE_ID”}， “属性”：{ “姓名”：{ "title": [{"text": {"content": "新任务"}}] }, “状态”：{ "select": {"name": "待办事项"} }, “优先”：{ “选择”：{“名称”：“高”} }, “截止日期”：{ “日期”：{“开始”：“2025-01-20”} } } }' |杰克 **Python - 页面操作：** # 在数据库中创建页面 new_page = notion.pages.create( 父={"database_id": "your-database-id"}, 属性={ “姓名”：{ "title": [{"text": {"content": "新任务"}}] }, “状态”：{ "select": {"name": "待办事项"} }, “优先”：{ “选择”：{“名称”：“高”} }, “截止日期”：{ “日期”：{“开始”：“2025-01-20”，“结束”：“2025-01-25”} }, “标签”：{ “多重选择”：[ {"name": "开发"}, {“名称”：“紧急”} ] }, “受让人”：{ "people": [{"id": "用户 ID"}] }, “注释”：{ "rich_text": [{"text": {"content": "此处的任务描述"}}] }, “完成”：{ “复选框”：错误 }, “金额”：{ “数量”：100 }, “网址”：{ “url”：“https://example.com” }, “电子邮件”：{ “电子邮件”：“user@example.com” } } ） print(f"已创建页面：{new_page['id']}") # 创建包含内容的页面（块） new_page = notion.pages.create( 父={"database_id": "your-database-id"}, 属性={ "Name": {"title": [{"text": {"content": "包含内容的页面"}}]} }, 孩子们=[ { “对象”：“块”， “类型”：“标题_2”， “标题_2”：{ "rich_text": [{"type": "text", "text": {"content": "概述"}}] } }, { “对象”：“块”， “类型”：“段落”， “段落”：{ "rich_text": [{"type": "text", "text": {"content": "这是内容。"}}] } }, { “对象”：“块”， “类型”：“待办事项”， “待办事项”：{ "rich_text": [{"type": "text", "text": {"content": "任务项"}}], “已检查”：错误 } } ] ） # 检索页面 page = notion.pages.retrieve(page_id="page-id") print(f"页：{页['属性']['名称']['标题'][0]['plain_text']}") # 更新页面属性概念.pages.update( page_id="页面id", 属性={ "状态": {"选择": {"名称": "完成"}}, “已完成”：{“复选框”：True} } ） # 存档页面（软删除）概念.pages.update( page_id="页面id", 已存档=真） # 恢复页面概念.pages.update( page_id="页面id", 已归档=假） ### 5\.块操作 **块类型：** # 段落 { “类型”：“段落”， “段落”：{ "rich_text": [{"type": "文本", "text": {"content": "文本内容"}}] } } # 标题 { “类型”：“标题_1”， “标题_1”：{ "rich_text": [{"type": "text", "text": {"content": "标题 1"}}] } } # 另外：标题_2、标题_3 # 项目符号列表 { “类型”：“项目符号列表项目”， “项目符号列表项目”：{ "rich_text": [{"type": "text", "text": {"content": "列表项"}}] } } # 编号列表 { “类型”：“编号列表项”， “编号列表项目”：{ "rich_text": [{"type": "text", "text": {"content": "项目 1"}}] } } # 待办事项 { “类型”：“待办事项”， “待办事项”：{ "rich_text": [{"type": "text", "text": {"content": "Task"}}], “已检查”：错误 } } # 切换 { “类型”：“切换”， “切换”：{ "rich_text": [{"type": "text", "text": {"content": "切换标题"}}], "children": [] # 嵌套块 } } # 代码块 { “类型”：“代码”， “代码”：{ "rich_text": [{"type": "text", "text": {"content": "print('hello')"}}], “语言”：“蟒蛇” } } # 报价 { “类型”：“报价”， “引用”：{ "rich_text": [{"type": "text", "text": {"content": "引用文字"}}] } } # 标注 { “类型”：“标注”， “标注”：{ "rich_text": [{"type": "text", "text": {"content": "重要说明"}}], “图标”：{“表情符号”：“💡”} } } # 分频器 { “类型”：“分隔符”， “分隔符”：{} } # 目录 { “类型”：“内容表”， “内容表”：{} } **Python - 块操作：** # 获取页面块（子级）块 = notion.blocks.children.list(block_id="page-id") 对于块中的块[“结果”]： print(f"块类型: {block['type']}") # 将块附加到页面 notion.blocks.children.append( block_id="页面id", 孩子们=[ { “对象”：“块”， “类型”：“标题_2”， “标题_2”：{ "rich_text": [{"type": "text", "text": {"content": "新部分"}}] } }, { “对象”：“块”， “类型”：“段落”， “段落”：{ “丰富的文本”：[ {"type": "text", "text": {"content": "一些"}}, {"type": "text", "text": {"content": "bold"}, "annotations": {"bold": True}}, {“类型”：“文本”，“文本”：{“内容”：“文本。”}} ] } }, { “对象”：“块”， “类型”：“项目符号列表项目”， “项目符号列表项目”：{ "rich_text": [{"type": "text", "text": {"content": "第一项"}}] } }, { “对象”：“块”， “类型”：“项目符号列表项目”， “项目符号列表项目”：{ "rich_text": [{"type": "text", "text": {"content": "第二项"}}] } } ] ） # 更新区块概念.块.更新( block_id =“块id”，段落={ "rich_text": [{"type": "text", "text": {"content": "更新内容"}}] } ） # 删除块 notion.blocks.delete(block_id="block-id") # 递归获取所有块 def get_all_blocks(block_id): """递归获取所有块""" 所有块= [] 有更多=真开始光标=无而 has_more：响应 = notion.blocks.children.list( 区块id=区块id, start_cursor=start_cursor, 页大小=100 ）对于响应中的块[“结果”]： all_blocks.append(块) if block.get("has_children"): 孩子= get_all_blocks（块[“id”]） all_blocks.extend（子级） has_more = 响应[“has_more”] start_cursor = response.get("next_cursor") 返回所有块 all_blocks = get_all_blocks("页面 ID") print(f"总块数: {len(all_blocks)}") ### 6\.富文本格式 **富文本结构：** # 基本文本 {"type": "text", "text": {"content": "纯文本"}} # 样式文本 { “类型”：“文本”， "text": {"content": "样式文本"}, “注释”：{ “大胆”：确实， “斜体”：错误， “删除线”：错误， “下划线”：错误， “代码”：错误， "color": "red" # 默认，灰色，棕色，橙色，黄色，绿色，蓝色，紫色，粉色，红色 } } # 链接 { “类型”：“文本”， “文本”：{ "内容": "点击这里", “链接”：{“网址”：“https://example.com”} } } # 提及用户 { “类型”：“提及”， “提及”：{ “类型”：“用户”， "user": {"id": "用户 ID"} } } # 提及页面 { “类型”：“提及”， “提及”：{ “类型”：“页面”， "page": {"id": "page-id"} } } # 提及日期 { “类型”：“提及”， “提及”：{ “类型”：“日期”， “日期”：{“开始”：“2025-01-17”} } } # 方程 { “类型”：“方程”， "方程": {"表达式": "E = mc^2"} } **Python - 富文本助手：** def create_rich_text（文本，粗体=假，斜体=假，代码=假，颜色=“默认”，链接=无）： """创建富文本对象的助手""" rt = { “类型”：“文本”， “文本”：{“内容”：文本}， “注释”：{ “粗体”：粗体， “斜体”：斜体， “删除线”：错误， “下划线”：错误， “代码”：代码， “颜色”：颜色 } } 如果链接： rt["text"]["link"] = {"url": 链接} 返回rt # 用法段落内容 = [ create_rich_text("这是"), create_rich_text("粗体", 粗体=True), 创建_rich_text（“和”）， create_rich_text("斜体", 斜体=True), create_rich_text("带有"的文本), create_rich_text("link", link="https://example.com"), 创建丰富的文本（“。”） ] notion.blocks.children.append( block_id="页面id", 孩子们=[{ “类型”：“段落”， “段落”：{“rich_text”：段落内容} }] ） ### 7\.关系和汇总 **创建相关数据库：** # 创建项目数据库 items_db = notion.databases.create( 父={"type": "page_id", "page_id": "父页面id"}, title=[{"type": "text", "text": {"content": "Projects"}}], 属性={ “姓名”：{“标题”：{}}， “状态”：{ “选择”：{ “选项”：[ {“名称”：“活动”，“颜色”：“绿色”}， {"name": "完成", "color": "灰色"} ] } } } ） # 创建与项目相关的任务数据库 task_db = notion.databases.create( 父={"type": "page_id", "page_id": "父页面id"}, title=[{"type": "text", "text": {"content": "Tasks"}}], 属性={ “姓名”：{“标题”：{}}， “状态”：{ “选择”：{ “选项”：[ {"name": "待办事项", "color": "灰色"}, {“名称”：“完成”，“颜色”：“绿色”} ] } }, “项目”：{ “关系”：{ “database_id”：projects_db[“id”]， “单一属性”：{} } } } ） # 将汇总添加到项目中以进行任务计数概念.数据库.更新( database_id=projects_db["id"], 属性={ “任务计数”：{ “汇总”：{ "relation_property_name": "Tasks", # 这是自动创建的 "rollup_property_name": "名称", “功能”：“计数” } } } ） # 创建链接到项目的任务概念.pages.create( 父={“database_id”：tasks_db [“id”]}，属性={ "名称": {"标题": [{"文本": {"内容": "任务1"}}]}, "状态": {"选择": {"名称": "待办事项"}}, “项目”：{“关系”：[{“id”：“项目页面id”}]} } ） ### 8\.搜索接口 **搜索操作：** # 搜索全部结果= notion.search() print(f"可访问的项目总数：{len(results['results'])}") # 使用查询进行搜索结果 = notion.search(query="项目计划") 对于结果中的项目[“结果”]： obj_type = 项目[“对象”] 如果 obj_type == “页面”： title = item["properties"].get("title", {}).get("title", [{}])[0].get("plain_text", "无标题") elif obj_type ==“数据库”： title = item["title"][0]["plain_text"] if item["title"] else "无标题" 打印（f“{obj_type}：{标题}”） # 只搜索页面结果=概念.搜索( 查询=“会议”， filter={“属性”：“对象”，“值”：“页面”} ） # 只搜索数据库结果=概念.搜索( 过滤器={“属性”：“对象”，“值”：“数据库”} ） # 排序搜索结果=概念.搜索( 查询=“报告”，排序={ “方向”：“下降”， “时间戳”：“最后编辑时间” } ） # 分页搜索 def search_all(查询=无，过滤器=无): """分页搜索""" 所有结果 = [] 有更多=真开始光标=无而 has_more：响应 = 概念. 搜索( 查询=查询，过滤器=过滤器， start_cursor=start_cursor, 页大小=100 ） all_results.extend(响应[“结果”]) has_more = 响应[“has_more”] start_cursor = response.get("next_cursor") 返回所有结果 ## 完整示例 ### 示例1：任务管理系统 #!/usr/bin/env python3 """notion_tasks.py - 使用 Notion 完成任务管理""" 从 notion_client 导入客户端从日期时间导入日期时间，时间增量导入操作系统概念 = Client(auth=os.environ["NOTION_API_KEY"]) 类NotionTaskManager： def __init__(自身,database_id): self.database_id = 数据库_id def create_task(self, 名称, 状态=“待办事项”, 优先级=“中”, due_date =无，标签=无，注释=无）： """创建新任务""" 属性={ "名称": {"标题": [{"文本": {"内容": 名称}}]}, "状态": {"选择": {"名称": 状态}}, "优先级": {"选择": {"名称": 优先级}} } 如果到期日期：属性["截止日期"] = {"日期": {"开始": due_date}} 如果标签：属性[“标签”] = { "multi_select": [{"name": tag} for 标签中的标签] } 如果注释：属性[“注释”] = { "rich_text": [{"text": {"content": 注释}}] } 返回 notion.pages.create( 父={"database_id": self.database_id}, 属性=属性） def get_tasks_by_status(自身, 状态): """获取给定状态的所有任务""" 返回 notion.databases.query( 数据库id=self.数据库id, 过滤器={ “财产”：“状态”， “选择”：{“等于”：状态} } ） def get_overdue_tasks(self): """获取所有逾期任务""" 今天 = datetime.now().strftime("%Y-%m-%d") 返回 notion.databases.query( 数据库id=self.数据库id, 过滤器={ “和”：[ {"property": "截止日期", "date": {"before": 今天}}, {“属性”：“状态”，“选择”：{“does_not_equal”：“完成”}} ] } ） def get_high_priority_tasks(self): """获取高优先级未完成任务""" 返回 notion.databases.query( 数据库id=self.数据库id, 过滤器={ “和”：[ {"property": "优先级", "select": {"equals": "高"}}, {“属性”：“状态”，“选择”：{“does_not_equal”：“完成”}} ] }, 排序=[ {“属性”：“到期日”，“方向”：“升序”} ] ） def Complete_task(self, page_id): """将任务标记为已完成""" 返回 notion.pages.update( page_id=page_id, 属性={ "状态": {"选择": {"名称": "完成"}}, “已完成”：{“复选框”：True} } ） def update_task_status（自身，page_id，状态）： """更新任务状态""" 返回 notion.pages.update( page_id=page_id, 属性={ “状态”：{“选择”：{“名称”：状态}} } ） def get_weekly_summary(self): """获取本周摘要""" week_ago = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d") #本周完成已完成= notion.databases.query( 数据库id=self.数据库id, 过滤器={ “和”：[ {"property": "状态", "select": {"equals": "完成"}}, {"property": "上次编辑时间", "date": {"after": week_ago}} ] } ） # 本周到期 next_week = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d") 即将推出= notion.databases.query( 数据库id=self.数据库id, 过滤器={ “和”：[ {"property": "截止日期", "date": {"on_or_before": next_week}}, {“属性”：“状态”，“选择”：{“does_not_equal”：“完成”}} ] } ）返回{ "completed_count": len(完成["结果"]), “即将到来的计数”：len（即将到来的[“结果”]）， “已完成”：已完成[“结果”]， “即将到来”：即将到来[“结果”] } # 用法如果 __name__ == "__main__": tm = NotionTaskManager("你的数据库 ID") # 创建任务任务 = tm.create_task( name="回顾第一季度报告", 优先级=“高”， due_date =“2025-01-20”， Tags=["工作", "季度"], 注释=“审查并提供反馈” ） print(f"已创建任务：{task['id']}") # 获取过期任务逾期= tm.get_overdue_tasks() print(f"\n过期任务: {len(overdue['results'])}") for t in overdue["results"]: 名称 = t["属性"]["名称"]["标题"][0]["纯文本"] 打印（f“ - {名称}”） # 每周总结摘要 = tm.get_weekly_summary() print(f"\n每周总结:") print(f" 已完成：{summary['completed_count']}") print(f" 即将到来：{summary['upcoming_count']}") ### 示例 2：内容管理系统 #!/usr/bin/env python3 """notion_cms.py - 使用 Notion 进行内容管理""" 从 notion_client 导入客户端从日期时间导入日期时间导入操作系统概念 = Client(auth=os.environ["NOTION_API_KEY"]) 类NotionCMS： def __init__(self, content_db_id,categories_db_id=None): self.content_db_id = content_db_id self.categories_db_id = 类别_db_id def create_article(self, 标题, content_blocks, status="草稿", 类别=无，标签=无，作者=无）： """创建新文章""" 属性={ "标题": {"标题": [{"文本": {"内容": 标题}}]}, "状态": {"选择": {"名称": 状态}}, “创建”：{“日期”：{“开始”：datetime.now().isoformat()}} } 如果类别：属性[“类别”] = {“选择”：{“名称”：类别}} 如果标签：属性[“标签”] = { "multi_select": [{"name": tag} for 标签中的标签] } 如果作者：属性[“作者”] = { "rich_text": [{"text": {"content": 作者}}] } 返回 notion.pages.create( 父={"database_id": self.content_db_id}, 属性=属性，孩子=内容块） def create_article_with_template(self, title, template="blog"): """从模板创建文章""" 模板={ “博客”：[ {"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "简介"}}]}}, {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， {"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "主要内容"}}]}}, {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， {"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "结论"}}]}}, {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， ], “教程”：[ {“类型”：“标注”，“标注”：{ "rich_text": [{"text": {"content": "先决条件："}}], "icon": {"emoji": "📋"} }}, {"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "概述"}}]}}, {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， {"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "第 1 步"}}]}}, {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， {“类型”：“代码”，“代码”：{“rich_text”：[{“文本”：{“内容”：“#此处代码”}}]，“语言”：“python”}}， {“type”：“heading_2”，“heading_2”：{“rich_text”：[{“text”：{“content”：“第2步”}}]}}， {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， {“type”：“heading_2”，“heading_2”：{“rich_text”：[{“text”：{“content”：“摘要”}}]}}， {“类型”：“段落”，“段落”：{“rich_text”：[{“文本”：{“内容”：“”}}]}}， ] } 返回 self.create_article( 标题=标题， content_blocks=templates.get(模板, templates["博客"]), 状态=“草稿” ） def get_published_articles(self, 类别=无, 限制=10): """获取发表的文章""" 过滤条件= [ {"property": "状态", "select": {"equals": "已发布"}} ] 如果类别：过滤器条件.append( {“属性”：“类别”，“选择”：{“等于”：类别}} ）返回 notion.databases.query( 数据库id=self.content_db_id, filter={“and”：filter_conditions} if len(filter_conditions) > 1 else filter_conditions[0], 排序=[{“属性”：“已创建”，“方向”：“降序”}]，页面大小=限制） defpublish_article(self, page_id): """发表文章""" 返回 notion.pages.update( page_id=page_id, 属性={ "Status": {"select": {"name": "已发布"}}, "发布日期": {"date": {"start": datetime.now().isoformat()}} } ） def export_article_to_markdown(self, page_id): """将文章内容导出为 Markdown""" 页面 = notion.pages.retrieve(page_id) 块 = notion.blocks.children.list(block_id=page_id) 标题 = 页面["属性"]["标题"]["标题"][0]["纯文本"] markdown = f"# {标题}\n\n" 对于块中的块[“结果”]： markdown += self._block_to_markdown(块) 返回降价 def _block_to_markdown(自身, 块): """将块转换为 Markdown""" 块类型=块[“类型”] 如果 block_type == "段落": 文本 = self._rich_text_to_markdown(块["段落"]["rich_text"]) 返回 f"{文本}\n\n" elif block_type == "heading_1": 文本 = self._rich_text_to_markdown(块["heading_1"]["rich_text"]) 返回 f"# {文本}\n\n" elif block_type == "heading_2": 文本 = self._rich_text_to_markdown(块["heading_2"]["rich_text"]) 返回 f"## {文本}\n\n" elif block_type == "heading_3": 文本 = self._rich_text_to_markdown(块["heading_3"]["rich_text"]) 返回 f"### {文本}\n\n" elif block_type == "bulleted_list_item": 文本 = self._rich_text_to_markdown(块["bulleted_list_item"]["rich_text"]) 返回 f"- {文本}\n" elif block_type == "numbered_list_item": 文本 = self._rich_text_to_markdown(块["numbered_list_item"]["rich_text"]) 返回 f"1.{文本}\n" elif block_type ==“代码”：文本 = self._rich_text_to_markdown(块["code"]["rich_text"]) lang = 块["代码"]["语言"] 返回 f"````{lang}\n{text}\n```\n\n" elif block_type == "引用": 文本 = self._rich_text_to_markdown(block["quote"]["rich_text"]) 返回 f"> {文本}\n\n" elif block_type ==“分隔符”：返回“---\n\n” 返回“” def _rich_text_to_markdown(self, rich_text): """将富文本数组转换为 Markdown""" 结果=“” 对于 rich_text 中的 rt： text = rt.get("文本", {}).get("内容", "") 注释 = rt.get("注释", {}) 如果注释.get(“粗体”): 文本 = f"**{文本}**" 如果注释.get(“斜体”): 文本 = f"*{文本}*" if 注释.get("代码"): 文本 = f"`{文本}`" if 注释.get("删除线"): 文本 = f"~~{文本}~~" 链接 = rt.get("文本", {}).get("链接") 如果链接：文本 = f"[{text}]({link['url']})" 结果 += 文本返回结果 # 用法如果 __name__ == "__main__": cms = NotionCMS("您的内容数据库 ID") # 从模板创建文章文章 = cms.create_article_with_template( title="Python 入门", 模板=“教程” ） print(f"已创建文章：{article['id']}") # 获取已发表的文章已发布 = cms.get_published_articles(limit=5) print(f"\n发表的文章: {len(published['results'])}") # 导出为 markdown md = cms.export_article_to_markdown("文章页面 ID") 打印（MD） ### 示例 3：项目仪表板 #!/usr/bin/env python3 """notion_dashboard.py - 使用 Notion 的项目仪表板""" 从 notion_client 导入客户端从日期时间导入日期时间，时间增量导入操作系统概念 = Client(auth=os.environ["NOTION_API_KEY"]) defgenerate_project_dashboard（projects_db_id，tasks_db_id）： """生成项目仪表板数据""" # 获取所有活动项目项目 = notion.databases.query( 数据库 ID = 项目数据库 ID, 过滤器={ “财产”：“状态”， “选择”：{“等于”：“活动”} } ）仪表板数据 = [] 对于项目中的项目[“结果”]：项目 ID = 项目[“ID”] 项目名称 = 项目["属性"]["名称"]["标题"][0]["纯文本"] # 获取该项目的任务任务 = notion.databases.query( 数据库id=tasks_db_id, 过滤器={ “财产”：“项目”， “关系”：{“包含”：project_id} } ） # 计算指标 Total_tasks = len(任务[“结果”]) 已完成 = sum(1 for t intasks["results"] if t["属性"]["状态"]["选择"]["名称"] == "完成") in_progress = sum(1 for t in 任务["结果"] if t["属性"]["状态"]["选择"]["名称"] == "进行中") # 获取过期任务今天 = datetime.now().strftime("%Y-%m-%d") 逾期 = sum(1 for t intasks["results"] if t["properties"].get("截止日期", {}).get("日期", {}).get("开始", "9999-99-99") < 今天和 t["属性"]["状态"]["选择"]["名称"] != "完成") 仪表板数据.append({ “项目 ID”：项目 ID， “项目名称”：项目名称， “总任务数”：总任务数， “已完成”：已完成， “进行中”：进行中， “待处理”：total_tasks - 已完成 - in_progress， “逾期”：逾期， "completion_rate": round(完成/total_tasks * 100, 1) 如果total_tasks > 0，否则为0 }) 返回仪表板数据 def create_dashboard_page（parent_page_id，dashboard_data）： """创建包含指标的仪表板页面""" # 仪表板构建块块= [ { “类型”：“标题_1”， “标题_1”：{ "rich_text": [{"text": {"content": f"项目仪表板 - {datetime.now().strftime('%Y-%m-%d')}"}}] } }, { “类型”：“分隔符”， “分隔符”：{} } ] 对于仪表板数据中的项目：块.扩展（[ { “类型”：“标题_2”， “标题_2”：{ “rich_text”：[{“text”：{“content”：项目[“project_name”]}}] } }, { “类型”：“标注”， “标注”：{ “丰富的文本”：[{ “文本”：{ "content": f"完成度: {project['completion_rate']}% | " f"任务：{项目['已完成']}/{项目['total_tasks']} | " f“进行中：{project['in_progress']} |” f“逾期：{项目['逾期']}” } }], "icon": {"emoji": "📊"} } } ]） # 添加进度条表示进度 = int(项目['完成率'] / 10) Progress_bar = "🟩" * 进度 + "⬜" * (10 - 进度) 块.追加（{ “类型”：“段落”， “段落”：{ "rich_text": [{"text": {"content": f"进度: {progress_bar}"}}] } }) # 创建页面返回 notion.pages.create( 父={“page_id”：parent_page_id}，属性={ "title": {"title": [{"text": {"content": "项目仪表板"}}]} }, 孩子=块） # 用法如果 __name__ == "__main__": 数据=生成项目仪表板（ projects_db_id="项目数据库id", tasks_db_id =“任务数据库id” ） print("项目仪表板") 打印（“=” * 50）对于数据中的项目： print(f"\n{项目['项目名称']}") print(f" 完成情况：{project['completion_rate']}%") print(f" 任务: {project['completed']}/{project['total_tasks']}") print(f" 进行中：{project['in_progress']}") print(f" 逾期: {project['overdue']}") ## 集成示例 ### 与 Slack 集成 #!/usr/bin/env python3 """slack_notion.py - 将 Slack 消息同步到 Notion""" 导入操作系统导入请求从 notion_client 导入客户端概念 = Client(auth=os.environ["NOTION_API_KEY"]) SLACK_WEBHOOK = os.environ["SLACK_WEBHOOK_URL"] def notification_slack_on_page_update(page_id, message): """Notion 页面更新时发送 Slack 通知""" 页面 = notion.pages.retrieve(page_id) 标题 = 页面["属性"]["名称"]["标题"][0]["纯文本"] 有效负载={ “块”：[ { “类型”：“部分”， “文本”：{ “类型”：“mrkdwn”， "text": f"*概念更新*: {标题}\n{消息}" } }, { “类型”：“动作”， “元素”：[{ “类型”：“按钮”， "text": {"type": "plain_text", "text": "在概念中查看"}, “url”：页面[“url”] }] } ] } requests.post(SLACK_WEBHOOK, json=有效负载) def create_notion_page_from_slack(database_id, 标题, 内容, 频道): """从 Slack 消息创建 Notion 页面""" 返回 notion.pages.create( 父={"database_id":database_id}, 属性={ "名称": {"标题": [{"文本": {"内容": 标题}}]}, “来源”：{“选择”：{“名称”：“Slack”}}， “频道”：{“rich_text”：[{“文本”：{“内容”：频道}}]} }, 孩子们=[{ “类型”：“段落”， “段落”：{ “rich_text”：[{“文本”：{“内容”：内容}}] } }] ） ### 与 GitHub 集成 #!/usr/bin/env python3 """github_notion.py - 将 GitHub 问题同步到 Notion""" 导入操作系统导入请求从 notion_client 导入客户端概念 = Client(auth=os.environ["NOTION_API_KEY"]) GITHUB_TOKEN = os.environ["GITHUB_TOKEN"] defsync_github_issues_to_notion(repo,database_id): """将 GitHub 问题同步到 Notion 数据库""" # 从 GitHub 获取问题响应 = requests.get( f“https://api.github.com/repos/{repo}/issues”， headers={"授权": f"令牌 {GITHUB_TOKEN}"} ）问题=response.json() 对于问题中的问题： # 检查Notion中是否已经存在问题现有= notion.databases.query( 数据库id=数据库id，过滤器={ "property": "GitHub ID", “数字”：{“等于”：问题[“数字”]} } ）属性={ "名称": {"标题": [{"文本": {"内容": 问题["标题"]}}]}, "GitHub ID": {"number": 问题["number"]}, “状态”：{ "select": {"name": "Open" if issues["state"] == "open" else "Closed"} }, "URL": {"url": 问题["html_url"]}, “标签”：{ "multi_select": [{"name": l["name"]} for l in issues["labels"]] } } 如果存在[“结果”]： # 更新现有的概念.pages.update( page_id=现有["结果"][0]["id"], 属性=属性）其他： # 创建新的概念.pages.create( 父={"database_id":database_id}, 属性=属性，孩子们=[{ “类型”：“段落”， “段落”：{ "rich_text": [{"text": {"content": issues.get("body", "") 或 ""}}] } }] ） print(f"已从 {repo} 同步 {len(issues)} 个问题") ## 最佳实践 ### 1\.速率限制导入时间从 functools 导入包装 defrate_limit(calls_per_second=3): """装饰器对 API 调用进行速率限制""" 最小间隔 = 1.0 / 每秒调用次数最后被叫 = [0.0] def 装饰器（函数）： @wraps(函数) def 包装器（*args，**kwargs）：经过 = time.time() - last_used[0] wait_time = min_interval - 经过如果 wait_time > 0: 时间.睡眠（等待时间）结果 = func(*args, **kwargs) 最后被叫[0] = time.time() 返回结果返回包装器返回装饰器 # 用法 @rate_limit(每秒调用次数=3) def api_call(func, *args, **kwargs): 返回 func(*args, **kwargs) ### 2\.错误处理从 notion_client 导入 APIResponseError def safe_notion_call(func, *args, max_retries=3, **kwargs): """使用重试逻辑执行 Notion API 调用""" 对于范围内的尝试（max_retries）：尝试：返回 func(*args, **kwargs) 除了 APIResponseError 为 e：如果 e.status == 429： # 速率有限 wait_time = int(e.headers.get("重试后", 60)) print(f"速率有限。等待 {wait_time}s...") 时间.睡眠（等待时间） elif e.status >= 500: # 服务器错误，重试 time.sleep(2 ** 尝试) 其他：提高除了异常 e：如果尝试 < max_retries - 1： time.sleep(2 ** 尝试) 其他：提高引发异常（f“重试 {max_retries} 次后失败”） ### 3\.批量操作 def batch_create_pages（database_id，pages_data，batch_size = 10）： """批量创建页面以避免速率限制""" 结果=[] 对于范围内的 i（0，len（pages_data），batch_size）：批次 = page_data[i:i + 批次大小] 对于批量的page_data：结果 = notion.pages.create( 父={"database_id":database_id}, 属性=page_data["属性"], 孩子= page_data.get（“孩子”，[]））结果.追加（结果）如果 i + 批量大小 < len(pages_data)： time.sleep(1) # 批次之间短暂暂停返回结果 ### 4\.缓存导入 json 从 pathlib 导入路径从日期时间导入日期时间，时间增量 CACHE_DIR = Path.home() / ".cache" / "概念" CACHE_TTL = timedelta(分钟=5) def get_cached_or_fetch(key, fetch_func, ttl=CACHE_TTL): """从缓存中获取或获取新数据""" CACHE_DIR.mkdir（父母= True，exist_ok = True） cache_file = CACHE_DIR / f"{key}.json" 如果cache_file.exists(): 数据 = json.loads(cache_file.read_text()) cached_at = datetime.fromisoformat(data["cached_at"]) 如果 datetime.now() - cached_at < ttl：返回数据[“值”] 值 = fetch_func() 缓存数据 = { "cached_at": datetime.now().isoformat(), “价值”：价值 } cache_file.write_text(json.dumps(cache_data, 默认=str)) 返回值 ## 故障排除 ### 常见问题 **问题：401 未经授权** # 验证 API 密钥卷曲-s“https://api.notion.com/v1/users/me”\ -H“授权：持有者$NOTION_API_KEY”\ -H“概念版本：2022-06-28” # 检查集成是否连接到页面/数据库 # 转到页面 > ... 菜单 > 连接 > 您的集成 **问题：404 未找到** # 确保集成可以访问该页面 # 集成必须显式连接到每个页面 # 对于数据库，检查数据库ID是否正确 # 数据库 ID 格式：32 个十六进制字符（带或不带连字符） **问题：400 错误请求** # 检查属性名称是否完全匹配（区分大小写） # 验证属性类型与数据库模式匹配 # 常见错误： # - 使用“title”而不是实际的标题属性名称 # - 错误的 select/multi_select 选项名称 # - 日期格式无效（使用 ISO 8601：“2025-01-17”） **问题：速率限制 (429)** # Notion 允许每秒约 3 个请求 # 实现指数退避 # 检查 Retry-After 标头以了解等待时间 ## 版本历史版本 |日期 |变化 ---|---|--- 1.0.0 | 2025-01-17 |具有全面 Notion API 覆盖的初始版本 ## 资源 * [Notion API 文档]() * [API 参考]() * [Python SDK]() * [JavaScript SDK]() * [集成库]() * [API 变更日志]() ** ** _此技能通过 Notion 的综合 API 实现强大的工作区自动化，支持数据库、页面、块、查询和集成模式。_

概念API

包含技能