技能名称: gsuite-sdk
详细描述:

Google Suite 技能

使用 gsuite-sdk 与 Google Workspace API（Gmail、Calendar、Drive、Sheets）交互的技能。

安装

bash
pip install gsuite-sdk

附带可选扩展：
bash
pip install gsuite-sdk[cloudrun] # 用于 Secret Manager
pip install gsuite-sdk[all] # 所有依赖

身份验证

首次使用（需要浏览器）

用户需要从 Google Cloud Console 获取 credentials.json，然后进行身份验证：

bash

通过 CLI

gsuite auth login

或通过 Python（会打开浏览器）

from gsuite_core import GoogleAuth auth = GoogleAuth() auth.authenticate()

完整指南请参阅 GETTING_CREDENTIALS.md。

后续会话

一旦完成身份验证，令牌会保存在本地并自动刷新：

python
from gsuite_core import GoogleAuth

auth = GoogleAuth()
if auth.is_authenticated():
# 准备就绪，可以使用
pass
else:
# 需要身份验证（会打开浏览器）
auth.authenticate()

Gmail

读取邮件

python
from gsuite_core import GoogleAuth
from gsuite_gmail import Gmail, query

auth = GoogleAuth()
gmail = Gmail(auth)

未读邮件

for msg in gmail.getunread(maxresults=10): print(f发件人: {msg.sender}) print(f主题: {msg.subject}) print(f日期: {msg.date}) print(f预览: {msg.body[:200]}...) print(---)

使用查询构建器搜索

mensajes = gmail.search( query.from_(notifications@github.com) & query.newer_than(days=7) )

标记为已读

msg.markasread()

发送邮件

python
gmail.send(
to=[收件人@example.com],
subject=邮件主题,
body=邮件内容,
)

带附件

gmail.send( to=[user@example.com], subject=报告, body=附件是报告。, attachments=[报告.pdf], )

Calendar

读取事件

python
from gsuite_core import GoogleAuth
from gsuite_calendar import Calendar

auth = GoogleAuth()
calendar = Calendar(auth)

今日事件

for event in calendar.get_today(): print(f{event.start.strftime(%H:%M)} - {event.summary})

未来7天

for event in calendar.get_upcoming(days=7): print(f{event.start}: {event.summary}) if event.location: print(f 📍 {event.location})

指定时间范围

from datetime import datetime events = calendar.get_events( time_min=datetime(2026, 2, 1), time_max=datetime(2026, 2, 28), )

创建事件

python
from datetime import datetime

calendar.create_event(
summary=团队会议,
start=datetime(2026, 2, 15, 10, 0),
end=datetime(2026, 2, 15, 11, 0),
location=会议室,
)

带参会者

calendar.create_event( summary=每周同步, start=datetime(2026, 2, 15, 14, 0), end=datetime(2026, 2, 15, 15, 0), attendees=[alice@company.com, bob@company.com], send_notifications=True, )

Drive

列出和下载文件

python
from gsuite_core import GoogleAuth
from gsuite_drive import Drive

auth = GoogleAuth()
drive = Drive(auth)

列出最近文件

for file in drive.listfiles(maxresults=20): print(f{file.name} ({file.mime_type}))

搜索

files = drive.list_files(query=name contains 报告)

下载

file = drive.get(文件ID) file.download(/tmp/文件.pdf)

上传文件

python

上传文件

uploaded = drive.upload(文档.pdf)
print(f链接: {uploaded.webviewlink})

上传到指定文件夹

uploaded = drive.upload(数据.xlsx, parent_id=文件夹ID)

创建文件夹

folder = drive.create_folder(2026年报告) drive.upload(q1.pdf, parent_id=folder.id)

Sheets

读取数据

python
from gsuite_core import GoogleAuth
from gsuite_sheets import Sheets

auth = GoogleAuth()
sheets = Sheets(auth)

打开电子表格

spreadsheet = sheets.open(电子表格ID)

读取工作表

ws = spreadsheet.worksheet(Sheet1) data = ws.get(A1:D10) # 列表的列表

以字典形式读取（第一行为表头）

records = ws.getallrecords()

[{姓名: Alice, 年龄: 30}, ...]

写入数据

python

更新单元格

ws.update(A1, 新值)

更新范围

ws.update(A1:C2, [ [姓名, 年龄, 城市], [Alice, 30, 纽约], ])

在末尾追加行

ws.append([ [Bob, 25, 洛杉矶], [Charlie, 35, 芝加哥], ])

CLI

如果你安装了 gsuite-cli：

bash

身份验证

gsuite auth login
gsuite auth status

Gmail

gsuite gmail list --unread gsuite gmail send --to user@example.com --subject 你好 --body 世界

Calendar

gsuite calendar today gsuite calendar list --days 7

Drive

gsuite drive list gsuite drive upload 文件.pdf

Sheets

gsuite sheets read 电子表格ID --range A1:C10

给代理的注意事项

1. 1. 首次身份验证需要浏览器 - 用户必须首次手动完成 OAuth
2. 令牌持久化 - 身份验证后，令牌保存在 tokens.db 中并自动刷新
3. 作用域 - 默认请求访问 Gmail、Calendar、Drive 和 Sheets。可以通过 --scopes 限制
4. 常见错误：

- CredentialsNotFoundError：缺少 credentials.json - TokenRefreshError：令牌过期且无法刷新（需要重新验证） - NotFoundError：资源不存在或没有权限