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，而是需要：

1. 在 Google Cloud Console 中创建 OAuth 客户端并拿到Client ID与Client Secret；
2. 在 Automatisch 中添加连接时填入上述凭据，然后跳转到 Google 授权页完成授权；
3. Automatisch 后端用授权码换取access_token与refresh_token并持久化保存；
4. 后续每次请求 Google API 时自动携带access_token，过期后自动用refresh_token刷新。

官方连接说明文档位于 connection.md，其中包含从创建项目到完成连接的 21 个步骤，下文将逐段展开，并结合仓库源码说明每个环节的底层实现。

一、在 Google Cloud Console 中创建项目并启用所需 API

步骤 1–7：创建项目、启用 People API 与 Google Drive API

打开 Google Cloud Console，按以下顺序操作：

1. 点击页面顶部的项目下拉菜单，选择New Project（新建项目）；
2. 为项目命名并点击Create（创建）；
3. 进入 API Library；
4. 在搜索栏搜索People API并点开，点击Enable（启用）；
5. 重复第 4、5 步，同样启用Google Drive API。

之所以必须启用People API，是因为 Automatisch 在认证 Google Drive 时会调用 Google People API 来获取当前账号信息，用于在连接列表中展示可读的账号标识。查看 get-current-user.js：

const getCurrentUser = async ($) => { const { data: currentUser } = await $.http.get( 'https://people.googleapis.com/v1/people/me?personFields=names,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 页面执行：

1. 用户类型选择External（外部），先以测试模式发布应用，点击Create；
2. 填写App Name（应用名称）、User Support Email（用户支持邮箱）与Developer Contact Information（开发者联系信息），点击Save and Continue；
3. 跳过添加 Scopes（授权范围），直接点击Save and Continue；
4. 由于发布状态为Testing，只有被添加的测试用户才能访问应用。点击Add Users并添加一个测试邮箱；
5. 点击Save and Continue完成同意屏幕配置。

说明：Agents 与流程运行时，Google 会在用户授权页面展示应用名称与范围。测试模式下仅限已添加的测试账号完成授权；若需要不限用户使用，可在同意屏幕完成后提交审核，将发布状态切换为In production。

从 Automatisch 侧看，Google Drive 连接实际申请的授权范围定义在 auth-scope.js：

const 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 页面：

1. 点击Create Credentials（创建凭据），选择OAuth client ID；
2. 应用类型选择Web application，填写Name；
3. 将 Automatisch 提供的OAuth Redirect URL复制到Authorized redirect URIs字段，点击Create；
4. 在弹出的对话框中复制Your Client ID，填入 Automatisch 的Client ID字段；
5. 复制Your Client Secret，填入 Automatisch 的Client Secret字段；
6. 点击 Automatisch 上的Submit，完成连接创建。

这里的OAuth Redirect URL不是手工拼写的，而是由 Automatisch 后端动态生成。查看 auth/index.js 中连接表单的三个字段定义：

字段 key	标签	类型	说明
oAuthRedirectUrl	OAuth Redirect URL	string（只读）	默认值{WEB_APP_URL}/app/google-drive/connections/add，支持点击复制（clickToCopy: true）
clientId	Client ID	string（必填）	来自 Google Cloud OAuth 客户端
clientSecret	Client Secret	string（必填）	来自 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. 生成授权 URL（generate-auth-url.js）

const 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 再换 token；
• access_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.js）

access_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_token>（token 类型由 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: offline（Automatisch 默认携带，无需额外配置）；
• 连接突然不可用：账号密码变更、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