google-sheets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Drive Google Sheets via

curl + jq

. The user's OAuth bearer token is in

$GOOGLE_SHEETS_TOKEN

; every call needs

Authorization: Bearer $GOOGLE_SHEETS_TOKEN

. Base URL:

https://sheets.googleapis.com/v4/spreadsheets

. The token carries

spreadsheets.readonly

(+ identity); writes need the broader

spreadsheets

scope.

Failures are

{"error":{"code","message","status"}}

— show verbatim.

= re-install.

403 PERMISSION_DENIED

on a write = read-only scope → re-connect with read+write.

The spreadsheet id is the

…/spreadsheets/d/<ID>/edit

segment of the URL.

bash

S="https://sheets.googleapis.com/v4/spreadsheets"; AUTH="Authorization: Bearer $GOOGLE_SHEETS_TOKEN"

通过

curl + jq

操作Google Sheets。用户的OAuth bearer token存储在

$GOOGLE_SHEETS_TOKEN

中；每次调用都需要携带

Authorization: Bearer $GOOGLE_SHEETS_TOKEN

请求头。基础URL：

https://sheets.googleapis.com/v4/spreadsheets

。该token包含

spreadsheets.readonly

（+身份验证）权限；写入操作需要更广泛的

spreadsheets

权限范围。

失败响应格式为

{"error":{"code","message","status"}}

— 需原样展示。

错误表示需要重新安装授权。写入时出现

403 PERMISSION_DENIED

错误表示当前为只读权限范围 → 需要重新连接并获取读写权限。

电子表格ID是URL中

…/spreadsheets/d/<ID>/edit

部分的

<ID>

。

bash

S="https://sheets.googleapis.com/v4/spreadsheets"; AUTH="Authorization: Bearer $GOOGLE_SHEETS_TOKEN"

Tabs + title

标签页 + 标题

curl -sS -H "$AUTH" "$S/SPREADSHEET_ID?fields=properties.title,sheets.properties(title,sheetId)"
| jq '{title: .properties.title, tabs: [.sheets[].properties.title]}'

undefined

curl -sS -H "$AUTH" "$S/SPREADSHEET_ID?fields=properties.title,sheets.properties(title,sheetId)"
| jq '{title: .properties.title, tabs: [.sheets[].properties.title]}'

undefined

Read / append / update values

读取 / 追加 / 更新数据

bash

ID="SPREADSHEET_ID"

bash

ID="SPREADSHEET_ID"

Read a range (A1 notation; values are rows of cells)

读取指定区域（A1表示法；返回值为单元格组成的行数组）

curl -sS -H "$AUTH" "$S/$ID/values/Sheet1!A1:D20" | jq '.values'

Append rows (confirm first). valueInputOption=USER_ENTERED parses formulas/dates.

追加行（请先确认）。valueInputOption=USER_ENTERED会解析公式/日期。

curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json"
-d '{"values":[["2026-06-21","Acme",4200]]}'
"$S/$ID/values/Sheet1!A1:append?valueInputOption=USER_ENTERED" | jq '.updates'

Update a fixed range: PUT /values/{range}?valueInputOption=USER_ENTERED

更新固定区域：PUT /values/{range}?valueInputOption=USER_ENTERED

curl -sS -X PUT -H "$AUTH" -H "Content-Type: application/json"
-d '{"values":[["done"]]}'
"$S/$ID/values/Sheet1!E2?valueInputOption=USER_ENTERED" | jq '.updatedCells'

undefined

curl -sS -X PUT -H "$AUTH" -H "Content-Type: application/json"
-d '{"values":[["done"]]}'
"$S/$ID/values/Sheet1!E2?valueInputOption=USER_ENTERED" | jq '.updatedCells'

undefined

Create a spreadsheet / add a tab

创建电子表格 / 添加标签页

bash

undefined

bash

undefined

New spreadsheet

创建新电子表格

curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json"
-d '{"properties":{"title":"Report 2026"}}' "$S" | jq '{spreadsheetId, spreadsheetUrl}'

Add a tab via batchUpdate (addSheet request)

通过batchUpdate添加标签页（addSheet请求）

curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json"
-d '{"requests":[{"addSheet":{"properties":{"title":"Q3"}}}]}'
"$S/$ID:batchUpdate" | jq '.replies'

undefined

curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json"
-d '{"requests":[{"addSheet":{"properties":{"title":"Q3"}}}]}'
"$S/$ID:batchUpdate" | jq '.replies'

undefined

Gotchas

注意事项

A1 notation:
```
Sheet1!A1:D20
```
; quote tab names with spaces as
```
'My Tab'!A1
```
.
```
valueInputOption=RAW
```
stores strings as-is;
```
USER_ENTERED
```
interprets them like the UI (numbers, dates,
```
=FORMULA
```
). Pick deliberately.
```
values
```
is row-major (
```
[[row1...],[row2...]]
```
); a missing trailing cell just comes back short — don't assume rectangular.

A1表示法：格式为
```
Sheet1!A1:D20
```
；若标签页名称包含空格，需用单引号包裹，如
```
'My Tab'!A1
```
。
```
valueInputOption=RAW
```
会按原样存储字符串；
```
USER_ENTERED
```
会像UI一样解析内容（数字、日期、
```
=FORMULA
```
公式）。请根据需求选择。
```
values
```
采用行优先顺序（
```
[[行1...],[行2...]]
```
）；缺失的末尾单元格会缩短返回结果 — 不要假设返回的是矩形结构。