Automatisch 接入 Google Drive:从零创建 OAuth 凭据到完成连接配置
Automatisch 接入 Google Drive:从零创建 OAuth 凭据到完成连接配置
本篇指南完整讲解如何在 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.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 页面执行:
- 用户类型选择 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.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 页面:
- 点击 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 | 标签 | 类型 | 说明 |
|---|---|---|---|
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 等)的同类问题。