Automatisch 接入 Notion 完整指南OAuth 集成创建、连接配置与源码级原理解析【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本指南以 Automatisch 官方文档 Notion 连接配置说明 为骨架完整讲解在 Notion 侧创建 OAuth 集成、在 Automatisch 侧完成连接建立的每一个步骤并结合 Notion 应用后端源码 揭示 OAuth 授权、凭证校验与连接复用的底层原理。读完本文你将能够在自己的 Automatisch 实例中独立完成 Notion 连接配置并理解连接建立后的请求是如何携带令牌访问 Notion API 的。准备工作你需要什么在开始配置之前请确认你具备以下条件一个可登录的 Notion 账户且对目标 Workspace 拥有创建集成的权限一个已成功安装并运行的 Automatisch 实例本地开发环境或自托管部署均可浏览器可以正常访问 Notion 的集成管理页面notion.so/my-integrations与你的 Automatisch Web 界面。:::info 本文以 Automatisch 仓库内 Notion 应用模块packages/backend/src/apps/notion为事实依据。若你使用的 Automatisch 版本较新界面文案可能略有差异但配置流程与参数含义保持一致。 :::第一步在 Notion 创建 OAuth Integration打开 Notion 的 My integrations 页面点击页面上的New integration按钮进入集成创建流程。在Name字段填写你的集成名称例如Automatisch点击Submit按钮提交。通过侧边栏进入Capabilities页面。在User capabilities区域勾选Read user information without email addresses选项然后保存更改。该权限用于 Automatisch 在建立连接后读取当前用户信息详见后文凭证校验一节。通过侧边栏进入Distribution页面。勾选Make this integration public复选框使集成对 OAuth 流程公开可用。在Organization information区域填写必要的组织信息字段组织名、网站等按 Notion 表单要求填写即可。将 Automatisch 提供的OAuth Redirect URL粘贴到 Notion 的Redirect URIs字段中。点击Submit按钮提交。在弹出的确认对话框中点击Continue确认将集成设为公开。第 6、10 步的公开化处理是 Notion OAuth 集成的硬性要求只有公开的集成才能参与 OAuth 授权码流程私有的集成只能通过 Notion 侧手动授权的方式使用无法由 Automatisch 发起授权跳转。第二步在 Automatisch 中填写 OAuth 凭证回到 Automatisch Web 界面在添加 Notion 连接的对话框{你的实例域名}/app/notion/connections/add中你会看到三个字段。它们由后端 auth 字段定义 声明字段类型必填说明OAuth Redirect URLstring只读是Automatisch 自动生成的回调地址形如{WEB_APP_URL}/app/notion/connections/add带clickToCopy复制按钮需要原样粘贴到 Notion 的 Redirect URIs 中Client IDstring是从 Notion 集成页复制的OAuth client IDClient Secretstring是从 Notion 集成页复制的OAuth client secret操作顺序复制 Automatisch 显示框内的OAuth Redirect URL可点击复制图标粘贴到 Notion 的 Redirect URIs 输入框中。回到 Notion 集成页面复制OAuth client ID和OAuth client secret两个值。在 Automatisch 中分别粘贴为Client ID与Client Secret。点击Submit按钮提交。凭证字段的源码级说明从源码结构看这三个字段具备如下特性理解它们有助于排查连接问题OAuth Redirect URL 是只读字段readOnly: true其值由模板变量{WEB_APP_URL}在部署时动态渲染。也就是说只要你的 Automatisch 实例外部访问地址确定该回调地址就是固定的——Notion 侧配置的 Redirect URI 必须与它逐字符完全一致包括https与结尾路径否则 OAuth 授权会因回调地址不匹配而失败。Client ID 与 Client Secret 都是必填且可编辑的普通字段required: true,readOnly: false。Automatisch 会将其加密存储并用于后续的 OAuth token 交换。第三步完成授权与连接建立填写完凭证并点击提交后Automatisch 会自动触发 OAuth 授权码流程整个过程由后端 generate-auth-url.js 与 verify-credentials.js 两个函数驱动1. 生成授权 URLAutomatisch 将用户重定向到 Notion 授权端点https://api.notion.com/v1/oauth/authorize?client_idClient IDredirect_uriOAuth Redirect URLresponse_typecodeowneruser从源码看generateAuthUrl会从 auth 字段定义中取出oAuthRedirectUrl的实际值连同用户填写的clientId一起拼装查询参数其中response_type固定为code、owner固定为user即按用户级授权方式申请访问。client_secret在此阶段不会出现在 URL 中——它只在下一步的 token 交换中作为 Basic 认证凭据使用。2. Notion 用户授权在 Notion 的授权页面选择目标 Workspace 并确认授权。Notion 会携带授权码code重定向回redirect_uri。3. 用授权码换取 Access TokenverifyCredentials收到code后向 Notion 的 token 端点发起POST /v1/oauth/tokenPOST https://api.notion.com/v1/oauth/token Authorization: Basic base64(Client ID:Client Secret) Content-Type: application/json { redirect_uri: OAuth Redirect URL, code: authorization_code, grant_type: authorization_code }注意源码中的两个细节Basic 认证头由clientId : clientSecret的 Base64 编码构成因此填错任意一个都会导致 token 交换失败该请求设置了additionalProperties.skipAddingAuthHeader: true让全局的addAuthHeader拦截器跳过此请求——这是授权码换 token与携带令牌访问业务 API的关键区分避免了在 Basic 认证请求上重复附加 Bearer 头。4. 凭证保存与用户信息回显换取成功后Automatisch 将access_token、bot_id、workspace_id、workspace_name、owner等字段存入该连接并调用 get-current-user.js 请求GET /v1/users/{owner.user.id}获取当前用户名称最终将连接显示名设为当前用户名 Workspace 名见 verify-credentials.js。这就是连接列表中能直接看到某某用户 某某 Workspace的原因。完成以上流程后连接即建立成功。之后便可在 Automatisch 中开始使用 Notion 连接来构建自动化流程。连接建立后请求如何携带身份每次 Automatisch 代表该连接调用 Notion API 时都会经过 index.js 中声明的beforeRequest钩子add-auth-header.js若连接中已保存accessToken自动为请求附加Authorization: Bearer accessToken头这也是上面提到的 token 交换请求通过skipAddingAuthHeader跳过该钩子的原因。add-notion-version-header.js为每次请求附加Notion-Version: 2022-06-28头。Notion API 要求所有请求显式声明 API 版本该值是当前应用实现所使用的版本。这两个钩子保证了连接建立后任何 Notion 动作Actions和触发器Triggers都能以最小配置直接访问 Notion API无需在每个步骤中重复填写令牌。连接可用性检查Automatisch 在后台会周期性检查已保存连接的可用性其逻辑位于 is-still-verified.js通过调用getCurrentUser请求当前用户信息只要返回的用户id存在就认为连接依然有效。这意味着如果集成在 Notion 侧被删除、或用户撤销了授权导致 token 失效该检查会失败Automatisch 会标记该连接为异常并提示重新连接该检查只依赖能取到用户信息这一事实属于轻量级校验。连接建立后可以做什么完成连接配置后你就可以在 Automatisch 流程编辑器中选择 Notion 应用使用以下能力参见 docs/pages/apps/notion触发器TriggersNew database items当所选数据库新增条目时触发Updated database items当所选数据库中的条目发生更新时触发。动作ActionsCreate database item在数据库中创建条目Create page在父页面下创建子页面Find database item按属性在数据库中查找条目Update database item更新数据库中的条目。这些触发器与动作的具体实现分别位于 triggers 与 actions 目录读者可以按需深入阅读源码。常见问题排查清单授权页面报 redirect_uri 不匹配检查 Notion 侧 Redirect URI 与 Automatisch 显示框中的 OAuth Redirect URL 是否逐字符一致注意协议、域名、端口与结尾斜杠。token 交换阶段报 401/403确认 Client ID 与 Client Secret 无误且集成已在 Distribution 页面设置为 public。授权时未显示目标 Workspace确认当前 Notion 账户对目标 Workspace 拥有创建集成的权限且集成尚未被删除。连接显示异常或需要重新连接通常是 token 失效所致可重新走一遍授权流程同时确认集成在 Notion 侧仍处于公开状态且 Capabilities 中勾选了读取用户信息权限。小结本文完整覆盖了 Automatisch 连接 Notion 的全部配置步骤从 Notion 侧创建公开 OAuth 集成、复制 Client ID / Client Secret到在 Automatisch 中填写 OAuth Redirect URL 并完成授权换取令牌。结合 Notion 应用源码 可以看出整个连接机制围绕授权码换令牌 → 保存连接凭证 → 自动附加 Bearer 头与版本头展开理解这条链路后你不仅能顺利配置 Notion 连接也能举一反三地理解 Automatisch 中其他 OAuth 应用的连接原理。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Automatisch 接入 Notion 完整指南：OAuth 集成创建、连接配置与源码级原理解析
Automatisch 接入 Notion 完整指南OAuth 集成创建、连接配置与源码级原理解析【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本指南以 Automatisch 官方文档 Notion 连接配置说明 为骨架完整讲解在 Notion 侧创建 OAuth 集成、在 Automatisch 侧完成连接建立的每一个步骤并结合 Notion 应用后端源码 揭示 OAuth 授权、凭证校验与连接复用的底层原理。读完本文你将能够在自己的 Automatisch 实例中独立完成 Notion 连接配置并理解连接建立后的请求是如何携带令牌访问 Notion API 的。准备工作你需要什么在开始配置之前请确认你具备以下条件一个可登录的 Notion 账户且对目标 Workspace 拥有创建集成的权限一个已成功安装并运行的 Automatisch 实例本地开发环境或自托管部署均可浏览器可以正常访问 Notion 的集成管理页面notion.so/my-integrations与你的 Automatisch Web 界面。:::info 本文以 Automatisch 仓库内 Notion 应用模块packages/backend/src/apps/notion为事实依据。若你使用的 Automatisch 版本较新界面文案可能略有差异但配置流程与参数含义保持一致。 :::第一步在 Notion 创建 OAuth Integration打开 Notion 的 My integrations 页面点击页面上的New integration按钮进入集成创建流程。在Name字段填写你的集成名称例如Automatisch点击Submit按钮提交。通过侧边栏进入Capabilities页面。在User capabilities区域勾选Read user information without email addresses选项然后保存更改。该权限用于 Automatisch 在建立连接后读取当前用户信息详见后文凭证校验一节。通过侧边栏进入Distribution页面。勾选Make this integration public复选框使集成对 OAuth 流程公开可用。在Organization information区域填写必要的组织信息字段组织名、网站等按 Notion 表单要求填写即可。将 Automatisch 提供的OAuth Redirect URL粘贴到 Notion 的Redirect URIs字段中。点击Submit按钮提交。在弹出的确认对话框中点击Continue确认将集成设为公开。第 6、10 步的公开化处理是 Notion OAuth 集成的硬性要求只有公开的集成才能参与 OAuth 授权码流程私有的集成只能通过 Notion 侧手动授权的方式使用无法由 Automatisch 发起授权跳转。第二步在 Automatisch 中填写 OAuth 凭证回到 Automatisch Web 界面在添加 Notion 连接的对话框{你的实例域名}/app/notion/connections/add中你会看到三个字段。它们由后端 auth 字段定义 声明字段类型必填说明OAuth Redirect URLstring只读是Automatisch 自动生成的回调地址形如{WEB_APP_URL}/app/notion/connections/add带clickToCopy复制按钮需要原样粘贴到 Notion 的 Redirect URIs 中Client IDstring是从 Notion 集成页复制的OAuth client IDClient Secretstring是从 Notion 集成页复制的OAuth client secret操作顺序复制 Automatisch 显示框内的OAuth Redirect URL可点击复制图标粘贴到 Notion 的 Redirect URIs 输入框中。回到 Notion 集成页面复制OAuth client ID和OAuth client secret两个值。在 Automatisch 中分别粘贴为Client ID与Client Secret。点击Submit按钮提交。凭证字段的源码级说明从源码结构看这三个字段具备如下特性理解它们有助于排查连接问题OAuth Redirect URL 是只读字段readOnly: true其值由模板变量{WEB_APP_URL}在部署时动态渲染。也就是说只要你的 Automatisch 实例外部访问地址确定该回调地址就是固定的——Notion 侧配置的 Redirect URI 必须与它逐字符完全一致包括https与结尾路径否则 OAuth 授权会因回调地址不匹配而失败。Client ID 与 Client Secret 都是必填且可编辑的普通字段required: true,readOnly: false。Automatisch 会将其加密存储并用于后续的 OAuth token 交换。第三步完成授权与连接建立填写完凭证并点击提交后Automatisch 会自动触发 OAuth 授权码流程整个过程由后端 generate-auth-url.js 与 verify-credentials.js 两个函数驱动1. 生成授权 URLAutomatisch 将用户重定向到 Notion 授权端点https://api.notion.com/v1/oauth/authorize?client_idClient IDredirect_uriOAuth Redirect URLresponse_typecodeowneruser从源码看generateAuthUrl会从 auth 字段定义中取出oAuthRedirectUrl的实际值连同用户填写的clientId一起拼装查询参数其中response_type固定为code、owner固定为user即按用户级授权方式申请访问。client_secret在此阶段不会出现在 URL 中——它只在下一步的 token 交换中作为 Basic 认证凭据使用。2. Notion 用户授权在 Notion 的授权页面选择目标 Workspace 并确认授权。Notion 会携带授权码code重定向回redirect_uri。3. 用授权码换取 Access TokenverifyCredentials收到code后向 Notion 的 token 端点发起POST /v1/oauth/tokenPOST https://api.notion.com/v1/oauth/token Authorization: Basic base64(Client ID:Client Secret) Content-Type: application/json { redirect_uri: OAuth Redirect URL, code: authorization_code, grant_type: authorization_code }注意源码中的两个细节Basic 认证头由clientId : clientSecret的 Base64 编码构成因此填错任意一个都会导致 token 交换失败该请求设置了additionalProperties.skipAddingAuthHeader: true让全局的addAuthHeader拦截器跳过此请求——这是授权码换 token与携带令牌访问业务 API的关键区分避免了在 Basic 认证请求上重复附加 Bearer 头。4. 凭证保存与用户信息回显换取成功后Automatisch 将access_token、bot_id、workspace_id、workspace_name、owner等字段存入该连接并调用 get-current-user.js 请求GET /v1/users/{owner.user.id}获取当前用户名称最终将连接显示名设为当前用户名 Workspace 名见 verify-credentials.js。这就是连接列表中能直接看到某某用户 某某 Workspace的原因。完成以上流程后连接即建立成功。之后便可在 Automatisch 中开始使用 Notion 连接来构建自动化流程。连接建立后请求如何携带身份每次 Automatisch 代表该连接调用 Notion API 时都会经过 index.js 中声明的beforeRequest钩子add-auth-header.js若连接中已保存accessToken自动为请求附加Authorization: Bearer accessToken头这也是上面提到的 token 交换请求通过skipAddingAuthHeader跳过该钩子的原因。add-notion-version-header.js为每次请求附加Notion-Version: 2022-06-28头。Notion API 要求所有请求显式声明 API 版本该值是当前应用实现所使用的版本。这两个钩子保证了连接建立后任何 Notion 动作Actions和触发器Triggers都能以最小配置直接访问 Notion API无需在每个步骤中重复填写令牌。连接可用性检查Automatisch 在后台会周期性检查已保存连接的可用性其逻辑位于 is-still-verified.js通过调用getCurrentUser请求当前用户信息只要返回的用户id存在就认为连接依然有效。这意味着如果集成在 Notion 侧被删除、或用户撤销了授权导致 token 失效该检查会失败Automatisch 会标记该连接为异常并提示重新连接该检查只依赖能取到用户信息这一事实属于轻量级校验。连接建立后可以做什么完成连接配置后你就可以在 Automatisch 流程编辑器中选择 Notion 应用使用以下能力参见 docs/pages/apps/notion触发器TriggersNew database items当所选数据库新增条目时触发Updated database items当所选数据库中的条目发生更新时触发。动作ActionsCreate database item在数据库中创建条目Create page在父页面下创建子页面Find database item按属性在数据库中查找条目Update database item更新数据库中的条目。这些触发器与动作的具体实现分别位于 triggers 与 actions 目录读者可以按需深入阅读源码。常见问题排查清单授权页面报 redirect_uri 不匹配检查 Notion 侧 Redirect URI 与 Automatisch 显示框中的 OAuth Redirect URL 是否逐字符一致注意协议、域名、端口与结尾斜杠。token 交换阶段报 401/403确认 Client ID 与 Client Secret 无误且集成已在 Distribution 页面设置为 public。授权时未显示目标 Workspace确认当前 Notion 账户对目标 Workspace 拥有创建集成的权限且集成尚未被删除。连接显示异常或需要重新连接通常是 token 失效所致可重新走一遍授权流程同时确认集成在 Notion 侧仍处于公开状态且 Capabilities 中勾选了读取用户信息权限。小结本文完整覆盖了 Automatisch 连接 Notion 的全部配置步骤从 Notion 侧创建公开 OAuth 集成、复制 Client ID / Client Secret到在 Automatisch 中填写 OAuth Redirect URL 并完成授权换取令牌。结合 Notion 应用源码 可以看出整个连接机制围绕授权码换令牌 → 保存连接凭证 → 自动附加 Bearer 头与版本头展开理解这条链路后你不仅能顺利配置 Notion 连接也能举一反三地理解 Automatisch 中其他 OAuth 应用的连接原理。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考