无浏览器环境下Gmail API Watch自动续期方案咨询

要在Cloud Run Job这类无浏览器环境中自动调用Gmail API的watch方法，核心是提前获取带刷新令牌的OAuth凭据，让服务能自动刷新访问令牌，无需用户手动授权。具体步骤如下：

1. 本地生成带刷新令牌的持久化凭据 #

在本地有浏览器的环境中，修改授权代码开启OAuth离线模式，强制获取refresh_token：

from google_auth_oauthlib.flow import InstalledAppFlow
from google.oauth2.credentials import Credentials

SCOPES = ['https://www.googleapis.com/auth/gmail.metadata']

# 初始化授权流，开启离线模式
flow = InstalledAppFlow.from_client_secrets_file(
    "client.json", 
    SCOPES, 
    redirect_uri="http://localhost"
)
# prompt='consent'确保即使之前授权过，也会返回refresh_token
creds = flow.run_local_server(
    port=0, 
    access_type='offline', 
    prompt='consent'
)

# 将凭据保存为JSON文件，后续需上传到GCP安全存储
with open("token.json", "w") as token_file:
    token_file.write(creds.to_json())

运行代码后，通过浏览器完成授权，生成的token.json包含长期有效的refresh_token（除非用户主动撤销授权）。

2. 修改Cloud Run Job脚本，自动刷新凭据 #

在watch脚本中，不再触发浏览器授权，而是加载保存的凭据并自动刷新过期的访问令牌：

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
from google.auth.transport.requests import Request
import json
import os

# 从GCP Secret Manager挂载的环境变量加载凭据
creds_json = os.environ.get("GMAIL_CREDENTIALS")
if not creds_json:
    raise ValueError("未配置GMAIL_CREDENTIALS环境变量")

creds = Credentials.from_authorized_user_info(json.loads(creds_json))

# 自动刷新过期的访问令牌
if creds.expired and creds.refresh_token:
    creds.refresh(Request())

# 调用Gmail API的watch方法
service = build('gmail', 'v1', credentials=creds)
response = service.users().watch(
    userId='me',
    body={
        'topicName': 'projects/你的项目ID/topics/你的PubSub主题名',
        'labelIds': ['INBOX'],  # 根据需求调整监听标签
        'labelFilterAction': 'include'
    }
).execute()

print(f"Watch续期成功，过期时间: {response['expiration']}")

3. 部署Cloud Run Job并配置定时触发 #

3.1 存储凭据到GCP Secret Manager #

将本地生成的token.json内容上传到GCP Secret Manager，创建名为gmail-watch-credentials的Secret，避免硬编码敏感信息。

3.2 创建Cloud Run Job #

• 将脚本打包为Docker镜像，上传到GCP Artifact Registry。
• 在GCP控制台创建Cloud Run Job，配置环境变量：从Secret Manager挂载gmail-watch-credentials为GMAIL_CREDENTIALS。
• 为Job的服务账号分配以下权限：
  • gmail.metadata访问权限
  • pubsub.topics.publish权限（用于Gmail推送消息到PubSub）
  • roles/secretmanager.secretAccessor（读取Secret Manager权限）

3.3 配置Cloud Scheduler定时任务 #

• 创建Cloud Scheduler任务，设置触发频率为每7天一次（Cron表达式：0 0 */7 * *）。
• 任务类型选择HTTP，目标设置为Cloud Run Job的触发URL，认证方式选择OIDC令牌，使用拥有Cloud Run Job执行权限的服务账号。

关键注意事项 #

• OAuth同意屏幕：若应用处于测试状态，需将相关测试用户或服务账号邮箱添加到OAuth同意屏幕的测试用户列表。
• 权限最小化：仅请求必要的Scope（如gmail.metadata），避免过度授权。
• 刷新令牌有效性：只要用户不主动撤销授权，refresh_token长期有效，无需重复授权。

内容的提问来源于stack exchange，提问作者Abhinav Ankur