Back to Details

google-sheets

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Sheets

Google Sheets

Read, write, and manage Google Sheets via OAuth authentication.
通过OAuth认证读写和管理Google Sheets。

Pre-Flight Check (ALWAYS FIRST)

预检检查（务必首先执行）

bash
python3 00-system/skills/google/google-master/scripts/google_auth.py --check --service sheets
Exit codes:
  • 0: Ready - proceed with user's request
  • 1: Need login - run 
    python3 00-system/skills/google/google-master/scripts/google_auth.py --login
  • 2: Missing deps - see ../google-master/references/setup-guide.md
bash
python3 00-system/skills/google/google-master/scripts/google_auth.py --check --service sheets
退出代码：
  • 0：准备就绪 - 继续处理用户请求
  • 1：需要登录 - 运行
    python3 00-system/skills/google/google-master/scripts/google_auth.py --login
  • 2：缺少依赖项 - 查看../google-master/references/setup-guide.md

Quick Reference

快速参考

Read Data

读取数据

bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py read <spreadsheet_id> "Sheet1!A1:D10"
bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py read <spreadsheet_id> "Sheet1!A1:D10"

Write Data

写入数据

bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py write <spreadsheet_id> "Sheet1!A1" --values '[["Name", "Amount"], ["Contract A", 5000]]'
bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py write <spreadsheet_id> "Sheet1!A1" --values '[["Name", "Amount"], ["Contract A", 5000]]'

Append Rows

追加行

bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py append <spreadsheet_id> "Sheet1!A:D" --values '[["New Row", "Data", "Here", "Now"]]'
bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py append <spreadsheet_id> "Sheet1!A:D" --values '[["New Row", "Data", "Here", "Now"]]'

Get Sheet Info

获取表格信息

bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py info <spreadsheet_id>
bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py info <spreadsheet_id>

List Spreadsheets

列出表格

bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py list --query "tracking"
bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py list --query "tracking"

Create Spreadsheet

创建表格

bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py create "New Spreadsheet" --sheets "Data" "Summary"
bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py create "New Spreadsheet" --sheets "Data" "Summary"

Common Workflows

常见工作流

Extract Data -> Update Sheet

提取数据 -> 更新表格

python
from sheets_operations import append_rows

data = [
    ["Contract A", "2024-01-15", 5000, "Active"],
    ["Contract B", "2024-02-01", 7500, "Pending"]
]
result = append_rows(spreadsheet_id, "Contracts!A:D", data)
print(f"Added {result['updated_rows']} rows")
python
from sheets_operations import append_rows

data = [
    ["Contract A", "2024-01-15", 5000, "Active"],
    ["Contract B", "2024-02-01", 7500, "Pending"]
]
result = append_rows(spreadsheet_id, "Contracts!A:D", data)
print(f"Added {result['updated_rows']} rows")

Batch Update Multiple Cells

批量更新多个单元格

python
from sheets_operations import batch_update

data = [
    {"range": "Sheet1!A1", "values": [["Header 1"]]},
    {"range": "Sheet1!B1", "values": [["Header 2"]]},
]
batch_update(spreadsheet_id, data)
python
from sheets_operations import batch_update

data = [
    {"range": "Sheet1!A1", "values": [["Header 1"]]},
    {"range": "Sheet1!B1", "values": [["Header 2"]]},
]
batch_update(spreadsheet_id, data)

Spreadsheet ID

表格ID

The spreadsheet ID is in the URL:
https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit
表格ID位于URL中：
https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

A1 Notation

A1表示法

ExampleMeaning
A1
Single cell
A1:B5
Range from A1 to B5
Sheet1!A1:B5
Range in specific sheet
A:A
Entire column A
1:1
Entire row 1
示例含义
A1
单个单元格
A1:B5
A1到B5的单元格范围
Sheet1!A1:B5
指定工作表中的单元格范围
A:A
整个A列
1:1
整个第1行

Available Operations

可用操作

OperationFunctionDescription
Read
read_range()
Read data from range
Write
write_range()
Write data to range
Append
append_rows()
Append rows to sheet
Clear
clear_range()
Clear values (keep formatting)
Batch
batch_update()
Update multiple ranges
Create
create_spreadsheet()
Create new spreadsheet
Info
get_spreadsheet_info()
Get metadata and sheets
List
list_spreadsheets()
List accessible spreadsheets
操作函数说明
读取
read_range()
读取指定范围的数据
写入
write_range()
向指定范围写入数据
追加
append_rows()
向工作表追加行
清空
clear_range()
清空值（保留格式）
批量更新
batch_update()
更新多个范围
创建
create_spreadsheet()
创建新表格
信息查询
get_spreadsheet_info()
获取元数据和工作表信息
列表查询
list_spreadsheets()
列出可访问的表格

Error Handling

错误处理

See ../google-master/references/error-handling.md for common errors and solutions.
常见错误及解决方案请查看../google-master/references/error-handling.md。

Setup

设置

First-time setup: ../google-master/references/setup-guide.md
Quick start:
  1. pip install google-auth google-auth-oauthlib google-api-python-client
  2. Create OAuth credentials in Google Cloud Console (enable Google Sheets API & Drive API, choose "Desktop app")
  3. Add to 
    .env
    file at Nexus root: 
    GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_PROJECT_ID=your-project-id
  4. Run 
    python3 00-system/skills/google/google-master/scripts/google_auth.py --login
首次设置：../google-master/references/setup-guide.md
快速开始：
  1. pip install google-auth google-auth-oauthlib google-api-python-client
  2. 在Google Cloud Console中创建OAuth凭据（启用Google Sheets API和Drive API，选择“桌面应用”）
  3. 在Nexus根目录的
    .env
    文件中添加以下内容： 
    GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_PROJECT_ID=your-project-id
  4. 运行
    python3 00-system/skills/google/google-master/scripts/google_auth.py --login