Back to Details

google-workspace

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Workspace Integration

Google Workspace 集成

Gmail and Google Calendar access via shared OAuth 2.0 authentication.
通过共享OAuth 2.0认证访问Gmail和Google Calendar。

Prerequisites

前提条件

  1. Python 3.10+ available
  2. Google Cloud project with Gmail API and Calendar API enabled
  3. OAuth 2.0 credentials (
    credentials.json
    ) downloaded
  4. Required packages: 
    google-api-python-client
    , 
    google-auth-httplib2
    , 
    google-auth-oauthlib
  1. 已安装Python 3.10及以上版本
  2. 已启用Gmail API和Calendar API的Google Cloud项目
  3. 已下载OAuth 2.0凭据文件（
    credentials.json
    ）
  4. 所需依赖包：
    google-api-python-client
    、
    google-auth-httplib2
    、
    google-auth-oauthlib

OAuth Setup

OAuth 配置

Step 1: Create Google Cloud Project

步骤1：创建Google Cloud项目

  1. Go to https://console.cloud.google.com/
  2. Create a new project or select existing
  3. Navigate to APIs & Services → Library
  4. Enable both Gmail API and Google Calendar API
  1. 访问https://console.cloud.google.com/
  2. 创建新项目或选择现有项目
  3. 进入APIs & Services → Library
  4. 启用Gmail API和Google Calendar API

Step 2: Configure OAuth Consent Screen

步骤2：配置OAuth同意屏幕

  1. Go to APIs & Services → OAuth consent screen
  2. Select External user type
  3. Add scopes: 
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.compose
    • https://www.googleapis.com/auth/gmail.modify
    • https://www.googleapis.com/auth/calendar.readonly
    • https://www.googleapis.com/auth/calendar.events
  4. Add user's email as a test user
  1. 进入APIs & Services → OAuth consent screen
  2. 选择External用户类型
  3. 添加以下权限范围： 
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.compose
    • https://www.googleapis.com/auth/gmail.modify
    • https://www.googleapis.com/auth/calendar.readonly
    • https://www.googleapis.com/auth/calendar.events
  4. 添加用户邮箱作为测试用户

Step 3: Create OAuth Credentials

步骤3：创建OAuth凭据

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. Select Desktop app as application type
  4. Download JSON and rename to 
    credentials.json
  1. 进入APIs & Services → Credentials
  2. 点击Create Credentials → OAuth client ID
  3. 选择Desktop app作为应用类型
  4. 下载JSON文件并重命名为
    credentials.json

Step 4: Install Dependencies

步骤4：安装依赖

bash
uv add google-api-python-client google-auth-httplib2 google-auth-oauthlib
bash
uv add google-api-python-client google-auth-httplib2 google-auth-oauthlib

Step 5: First Authentication

步骤5：首次认证

Run any script - it will open a browser for OAuth consent. A 
token.json
is saved for future use.
运行任意脚本 - 会打开浏览器进行OAuth授权。授权后会生成
token.json
文件，供后续使用。

Gmail Operations

Gmail 操作

Search Emails

搜索邮件

bash
uv run python tools/google-workspace/scripts/search_emails.py "from:someone@example.com" --credentials ./credentials.json
bash
uv run python tools/google-workspace/scripts/search_emails.py "from:someone@example.com" --credentials ./credentials.json

Read Email Content

读取邮件内容

bash
uv run python tools/google-workspace/scripts/read_email.py <message_id> --credentials ./credentials.json
bash
uv run python tools/google-workspace/scripts/read_email.py <message_id> --credentials ./credentials.json

Create Draft

创建草稿

bash
uv run python tools/google-workspace/scripts/create_draft.py \
  --to "recipient@example.com" \
  --subject "Subject line" \
  --body "Email body" \
  --credentials ./credentials.json
bash
uv run python tools/google-workspace/scripts/create_draft.py \
  --to "recipient@example.com" \
  --subject "Subject line" \
  --body "Email body" \
  --credentials ./credentials.json

Find Emails Needing Reply

查找需要回复的邮件

bash
uv run python tools/google-workspace/scripts/needs_reply.py --credentials ./credentials.json
bash
uv run python tools/google-workspace/scripts/needs_reply.py --credentials ./credentials.json

Calendar Operations

日历操作

List Calendars

列出日历

bash
uv run python tools/google-workspace/scripts/list_calendars.py --credentials ./credentials.json
bash
uv run python tools/google-workspace/scripts/list_calendars.py --credentials ./credentials.json

Search Events

搜索事件

bash
undefined
bash
undefined

Search by text

按文本搜索

uv run python tools/google-workspace/scripts/search_events.py "meeting" --credentials ./credentials.json
uv run python tools/google-workspace/scripts/search_events.py "meeting" --credentials ./credentials.json

Search by date range

按日期范围搜索

uv run python tools/google-workspace/scripts/search_events.py --start "2024-01-15" --end "2024-01-20" --credentials ./credentials.json
undefined
uv run python tools/google-workspace/scripts/search_events.py --start "2024-01-15" --end "2024-01-20" --credentials ./credentials.json
undefined

Check Availability

查看空闲时间

bash
uv run python tools/google-workspace/scripts/find_busy.py \
  --start "2024-01-15T09:00:00" \
  --end "2024-01-15T17:00:00" \
  --credentials ./credentials.json
bash
uv run python tools/google-workspace/scripts/find_busy.py \
  --start "2024-01-15T09:00:00" \
  --end "2024-01-15T17:00:00" \
  --credentials ./credentials.json

Create Event

创建事件

bash
uv run python tools/google-workspace/scripts/create_event.py \
  --summary "Team Meeting" \
  --start "2024-01-15T10:00:00" \
  --end "2024-01-15T11:00:00" \
  --attendees "alice@example.com,bob@example.com" \
  --credentials ./credentials.json
Options: 
--description
, 
--location
, 
--timezone
, 
--calendar
bash
uv run python tools/google-workspace/scripts/create_event.py \
  --summary "Team Meeting" \
  --start "2024-01-15T10:00:00" \
  --end "2024-01-15T11:00:00" \
  --attendees "alice@example.com,bob@example.com" \
  --credentials ./credentials.json
可选参数： 
--description
、
--location
、
--timezone
、
--calendar

Scripts Reference

脚本参考

Gmail:
  • gmail_auth.py
    - Gmail authentication utilities
  • search_emails.py
    - Search inbox with Gmail query syntax
  • read_email.py
    - Read email content by message ID
  • create_draft.py
    - Create draft emails
  • needs_reply.py
    - Find emails awaiting response
Calendar:
  • calendar_auth.py
    - Calendar authentication utilities
  • list_calendars.py
    - List accessible calendars
  • search_events.py
    - Search events by text/date
  • find_busy.py
    - Check free/busy periods
  • create_event.py
    - Create calendar events
Gmail相关：
  • gmail_auth.py
    - Gmail认证工具类
  • search_emails.py
    - 使用Gmail查询语法搜索收件箱
  • read_email.py
    - 通过邮件ID读取邮件内容
  • create_draft.py
    - 创建邮件草稿
  • needs_reply.py
    - 查找待回复的邮件
日历相关：
  • calendar_auth.py
    - 日历认证工具类
  • list_calendars.py
    - 列出可访问的日历
  • search_events.py
    - 按文本/日期搜索事件
  • find_busy.py
    - 查看空闲/忙碌时段
  • create_event.py
    - 创建日历事件

Common Workflows

常见工作流

Schedule a Meeting

安排会议

  1. Search calendar for availability: 
    search_events.py --start ... --end ...
  2. Create event: 
    create_event.py --summary "..." --start ... --end ...
  1. 搜索日历空闲时间：
    search_events.py --start ... --end ...
  2. 创建会议事件：
    create_event.py --summary "..." --start ... --end ...

Reply to Important Emails

回复重要邮件

  1. Find emails needing reply: 
    needs_reply.py
  2. Read specific email: 
    read_email.py <id>
  3. Create draft response: 
    create_draft.py --to ... --subject "Re: ..."
  1. 查找待回复邮件：
    needs_reply.py
  2. 读取指定邮件：
    read_email.py <id>
  3. 创建回复草稿：
    create_draft.py --to ... --subject "Re: ..."