Automatisch 接入 Google Drive：从零创建 OAuth 凭据到完成连接配置

Automatisch 接入 Google Drive：从零创建 OAuth 凭据到完成连接配置

发布时间：2026/9/14 14:53:59
Automatisch 接入 Google Drive：从零创建 OAuth 凭据到完成连接配置 Automatisch 接入 Google Drive从零创建 OAuth 凭据到完成连接配置【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本篇指南完整讲解如何在 Automatisch 中建立 Google Drive 连接从 Google Cloud Console 创建项目、启用 API、配置 OAuth 同意屏幕到生成 OAuth 客户端凭据并在 Automatisch 中完成认证。读完本文你将掌握 Google Drive OAuth 2.0授权码模式在 Automatisch 中的完整落地流程并能理解其背后由源码支撑的令牌刷新、凭据校验与请求鉴权机制。前置认知Google Drive 连接在 Automatisch 中的工作方式Google Drive 是 Automatisch 内置的应用之一。在 google-drive 应用定义 中可以看到其基本注册信息应用名Google Drive、唯一 key 为google-drive、supportsConnections: true即该应用需要通过「连接Connection」保存用户的 OAuth 凭据后才能被流程使用。与普通 API Key 不同Google Drive 走的是OAuth 2.0 授权码模式Authorization Code Flow。这意味着连接建立并非只填一个 Token而是需要在 Google Cloud Console 中创建 OAuth 客户端并拿到Client ID与Client Secret在 Automatisch 中添加连接时填入上述凭据然后跳转到 Google 授权页完成授权Automatisch 后端用授权码换取access_token与refresh_token并持久化保存后续每次请求 Google API 时自动携带access_token过期后自动用refresh_token刷新。官方连接说明文档位于 connection.md其中包含从创建项目到完成连接的 21 个步骤下文将逐段展开并结合仓库源码说明每个环节的底层实现。一、在 Google Cloud Console 中创建项目并启用所需 API步骤 1–7创建项目、启用 People API 与 Google Drive API打开 Google Cloud Console按以下顺序操作点击页面顶部的项目下拉菜单选择New Project新建项目为项目命名并点击Create创建进入 API Library在搜索栏搜索People API并点开点击Enable启用重复第 4、5 步同样启用Google Drive API。之所以必须启用People API是因为 Automatisch 在认证 Google Drive 时会调用 Google People API 来获取当前账号信息用于在连接列表中展示可读的账号标识。查看 get-current-user.jsconst getCurrentUser async ($) { const { data: currentUser } await $.http.get( https://people.googleapis.com/v1/people/me?personFieldsnames,emailAddresses ); return currentUser; };它会请求当前登录用户的names与emailAddresses字段随后在 verify-credentials.js 中提取主姓名与主邮箱拼成displayName - email格式写入screenName作为连接列表中的显示名称const { displayName } currentUser.names.find( (name) name.metadata.primary ); const { value: email } currentUser.emailAddresses.find( (emailAddress) emailAddress.metadata.primary ); await $.auth.set({ // ... screenName: ${displayName} - ${email}, });同时is-still-verified.js 也复用 People API 来判断连接是否仍然有效——只要people/me能返回resourceName就认为该连接可用const isStillVerified async ($) { const currentUser await getCurrentUser($); return !!currentUser.resourceName; };因此如果创建项目时漏掉 People API连接校验与用户信息展示都会失败。二、配置 OAuth 同意屏幕Consent Screen步骤 8–13配置同意屏幕并添加测试用户在 OAuth consent screen 页面执行用户类型选择External外部先以测试模式发布应用点击Create填写App Name应用名称、User Support Email用户支持邮箱与Developer Contact Information开发者联系信息点击Save and Continue跳过添加 Scopes授权范围直接点击Save and Continue由于发布状态为Testing只有被添加的测试用户才能访问应用。点击Add Users并添加一个测试邮箱点击Save and Continue完成同意屏幕配置。说明Agents 与流程运行时Google 会在用户授权页面展示应用名称与范围。测试模式下仅限已添加的测试账号完成授权若需要不限用户使用可在同意屏幕完成后提交审核将发布状态切换为In production。从 Automatisch 侧看Google Drive 连接实际申请的授权范围定义在 auth-scope.jsconst authScope [ https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile, ];即完整读写 Google Drive 文件、以及读取用户的邮箱与基本资料三个 Scope。这三个 Scope 会在生成授权 URL 时以空格连接后拼入scope参数也会在刷新令牌后再次写回因此步骤 11 中「跳过 scopes」并不会影响实际授权内容——实际申请范围由 Automatisch 后端在发起 OAuth 授权时统一携带。三、创建 OAuth 客户端并回填凭据步骤 14–19创建 Web 应用类型的 OAuth Client ID进入 Credentials 页面点击Create Credentials创建凭据选择OAuth client ID应用类型选择Web application填写Name将 Automatisch 提供的OAuth Redirect URL复制到Authorized redirect URIs字段点击Create在弹出的对话框中复制Your Client ID填入 Automatisch 的Client ID字段复制Your Client Secret填入 Automatisch 的Client Secret字段点击 Automatisch 上的Submit完成连接创建。这里的OAuth Redirect URL不是手工拼写的而是由 Automatisch 后端动态生成。查看 auth/index.js 中连接表单的三个字段定义字段 key标签类型说明oAuthRedirectUrlOAuth Redirect URLstring只读默认值{WEB_APP_URL}/app/google-drive/connections/add支持点击复制clickToCopy: trueclientIdClient IDstring必填来自 Google Cloud OAuth 客户端clientSecretClient Secretstring必填来自 Google Cloud OAuth 客户端其中oAuthRedirectUrl被标记为readOnly: true且required: true其值为{WEB_APP_URL}/app/google-drive/connections/add——部署时WEB_APP_URL会被替换为当前实例的 Web 应用地址。必须保证该地址与 Google Cloud 中填写的 Authorized redirect URIs 完全一致否则 OAuth 授权回调会因 redirect_uri 不匹配而被 Google 拒绝。这也是为什么文档强调要从 Automatisch 复制该地址而非自行输入。四、提交连接后发生的底层认证流程点击Submit并不是简单保存字符串而是触发 Automatisch 与 Google OAuth 服务端的一次完整握手。整个过程由三个认证模块协作完成1. 生成授权 URLgenerate-auth-url.jsconst searchParams new URLSearchParams({ client_id: $.auth.data.clientId, redirect_uri: redirectUri, prompt: select_account consent, scope: authScope.join( ), response_type: code, access_type: offline, }); const url https://accounts.google.com/o/oauth2/v2/auth?${searchParams.toString()};关键参数说明response_type: code采用授权码模式先换取 code 再换 tokenaccess_type: offline必须携带。只有 offline 模式才会返回refresh_token保证 access_token 过期后 Automatisch 能自主续期无需用户再次授权prompt: select_account consent强制用户选择账号并弹出同意页面scope上文提及的三个 Scope 以空格拼接。2. 用授权码换取令牌verify-credentials.js用户完成 Google 授权页跳回后Automatisch 携带code向 Google Token Endpoint 发起请求const { data } await $.http.post(https://oauth2.googleapis.com/token, { client_id: $.auth.data.clientId, client_secret: $.auth.data.clientSecret, code: $.auth.data.code, grant_type: authorization_code, redirect_uri: redirectUri, });拿到access_token、refresh_token、expires_in等令牌数据后先保存访问令牌再调用 People API 读取账号信息最终把clientId、clientSecret、scope、idToken、expiresIn、refreshToken、resourceName、screenName全部写入连接数据中。3. 令牌自动刷新refresh-token.jsaccess_token 有效期通常为 1 小时。当它过期时Automatisch 会用持久化的refresh_token发起刷新请求const params new URLSearchParams({ client_id: $.auth.data.clientId, client_secret: $.auth.data.clientSecret, grant_type: refresh_token, refresh_token: $.auth.data.refreshToken, }); const { data } await $.http.post( https://oauth2.googleapis.com/token, params.toString() ); await $.auth.set({ accessToken: data.access_token, expiresIn: data.expires_in, scope: authScope.join( ), tokenType: data.token_type, });刷新成功后仅更新access_token等字段原始refresh_token保持不变因此一次授权即可长期使用。五、连接成功后请求如何携带鉴权信息连接建立后Automatisch 执行 Google Drive 相关触发器或动作时会通过 add-auth-header.js 为每个出站请求注入鉴权头const addAuthHeader ($, requestConfig) { if ($.auth.data?.accessToken) { requestConfig.headers.Authorization ${$.auth.data.tokenType} ${$.auth.data.accessToken}; } return requestConfig; };该中间件被注册在应用定义的beforeRequest钩子中见 index.js意味着所有发往 Google API 的请求都会自动带上Authorization: Bearer access_tokentoken 类型由 Google 返回通常为Bearer。应用 API 请求的基地址为 index.js 中声明的https://www.googleapis.com/drive而文件页面的基地址为https://drive.google.com。例如「列出文件夹」「列出 Drive」这类动态数据能力见 dynamic-data/index.js以及「新文件」「文件夹内新文件」「新文件夹」「更新文件」四个触发器见 triggers/index.js都会经由上述鉴权链路访问 Google Drive API。六、验证连接与常见问题排查验证连接状态连接创建成功后Automatisch 会周期性调用 is-still-verified.js 检查连接是否仍然有效通过 People API 是否返回resourceName判断。若测试账号被删除、refresh_token 被吊销或应用被停止连接会显示为失效状态需要重新授权。常见问题清单redirect_uri_mismatch 错误Automatisch 里的 OAuth Redirect URL 与 Google Cloud 的 Authorized redirect URIs 不一致。请重新从 Automatisch 复制该地址并覆盖填入 Google Cloud用户无法授权同意屏幕处于 Testing 状态需在Add Users中添加测试邮箱或提交审核后将发布状态改为 In production看不到账号名/邮箱未启用 People API回到 API Library 启用 People API 后重新创建连接access_token 频繁失效确认创建 OAuth 客户端时应用类型为Web application且授权请求包含access_type: offlineAutomatisch 默认携带无需额外配置连接突然不可用账号密码变更、refresh_token 被 Google 撤销如用户主动取消授权都会导致连接失效需在 Automatisch 中删除后重新授权。总结在 Automatisch 中接入 Google Drive 的完整链路是Google Cloud 创建项目并启用 People API 与 Google Drive API → 配置 OAuth 同意屏幕并添加测试用户 → 创建 Web 应用型 OAuth 客户端 → 将 Client ID / Client Secret 填入 Automatisch 连接表单 → 完成 OAuth 授权后由后端自动维护令牌生命周期。从源码层面看这套连接机制由 auth/index.js 统一定义表单字段由generateAuthUrl、verifyCredentials、refreshToken、isStillVerified四个模块分别负责授权、换票、续期与健康检查最终由addAuthHeader保证所有业务请求自动鉴权。理解这一机制后你不仅能在 Automatisch 中正确配置 Google Drive 连接也能举一反三地排查其他 OAuth 类应用如 Gmail、Google Sheets 等的同类问题。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考