读取并更新 Sheets 单元格

读取测试表的指定矩形区域，再用 RAW 模式覆盖该区域的值。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

访问令牌含 https://www.googleapis.com/auth/spreadsheets；写入者对目标表格有编辑权限。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

GOOGLE_ACCESS_TOKEN: 先执行本站本平台的获取与刷新用户令牌场景；令牌必须含当前场景要求的 scope，不能使用 API Key。
GOOGLE_SPREADSHEET_ID: 电子表格文件 ID，不是 URL 里的 gid 工作表数字；这里是虚构值。

export GOOGLE_ACCESS_TOKEN='replace_with_oauth_access_token'
export GOOGLE_SPREADSHEET_ID='example_spreadsheet_id'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
先在本站 OAuth 场景申请 spreadsheets 范围，得到 GOOGLE_ACCESS_TOKEN。
02
创建自己的测试表，将一个工作表命名为 Sheet1；从 /spreadsheets/d/ 与 /edit 之间取得文件 ID，设为 GOOGLE_SPREADSHEET_ID。
03
先运行读取操作，确认 Sheet1!A1:B2 不是要保留的数据；更新操作会覆盖这些单元格。
04
编辑 values 后执行更新；再运行同一个读取操作确认结果。不要用此例覆盖生产报表。

调用 01

读取 A1:B2

A1 范围已 URL 编码；默认按行返回并使用格式化值。

GEThttps://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2

请求头

Authorization: Bearer ${GOOGLE_ACCESS_TOKEN}

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`spreadsheetId`Path	string必填	电子表格文件 ID。
`range`Path	string必填	本例 Sheet1!A1:B2；特殊工作表名需正确引用并 URL 编码。
`valueRenderOption`Query	string可选	默认 FORMATTED_VALUE；需要原始数字可设 UNFORMATTED_VALUE，读公式可设 FORMULA。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2" \
  --header "Authorization: Bearer ${GOOGLE_ACCESS_TOKEN}"

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2")
headers = {
    "Authorization": expand("Bearer ${GOOGLE_ACCESS_TOKEN}"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${GOOGLE_ACCESS_TOKEN}"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意，ID、文本和数字均为虚构，非接口实测结果。尾部空行/空列可能省略，values 不能假设总有两行两列。以下为结构示意，非本站实测结果。

{
  "range": "Sheet1!A1:B2",
  "majorDimension": "ROWS",
  "values": [
    [
      "项目",
      "状态"
    ],
    [
      "示例任务",
      "待处理"
    ]
  ]
}

常见错误与排查

HTTP 401访问令牌缺失、无效或已过期。: 按本站授权场景使用 refresh_token 刷新；不要把 client_secret 或 API Key 当成 access_token。
HTTP 403权限不足、组织策略限制或达到用户配额。: 读取 error.details/reason；核对已授权 scope、文件共享权限和项目配额，不能只重复授权同一个 scope。
HTTP 429达到服务请求频率限制。: 采用带随机抖动的指数退避，限制重试次数，并减少批量轮询。

调用注意

读取 GET 不带请求体；只读需求可改申请 spreadsheets.readonly，但该权限不能执行下一步写入。

Sheets spreadsheets.values.get Sheets ValueRange 请求与响应

调用 02

覆盖 A1:B2 的值

RAW 使文字按原样存入，不按用户输入规则自动解析为公式或日期。

PUThttps://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2?valueInputOption=RAW

请求头

Authorization: Bearer ${GOOGLE_ACCESS_TOKEN}
Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`range`Path	string必填	目标区域，本例 Sheet1!A1:B2。
`valueInputOption`Query	string必填	RAW 或 USER_ENTERED；本例 RAW，避免自动解析公式。
`majorDimension`请求体	string可选	本例 ROWS；每个内层数组对应一行。
`values`请求体	array[]必填	写入的行列值；这里是 2×2 的测试数据。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cat > request-body.json <<'JSON'
{
  "range": "Sheet1!A1:B2",
  "majorDimension": "ROWS",
  "values": [
    [
      "项目",
      "状态"
    ],
    [
      "示例任务",
      "已同步"
    ]
  ]
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request PUT \
  --url "https://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2?valueInputOption=RAW" \
  --header "Authorization: Bearer ${GOOGLE_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2?valueInputOption=RAW")
headers = {
    "Authorization": expand("Bearer ${GOOGLE_ACCESS_TOKEN}"),
    "Content-Type": expand("application/json"),
}
body = {
    "range": "Sheet1!A1:B2",
    "majorDimension": "ROWS",
    "values": [
        [
            "项目",
            "状态",
        ],
        [
            "示例任务",
            "已同步",
        ],
    ],
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="PUT")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://sheets.googleapis.com/v4/spreadsheets/${GOOGLE_SPREADSHEET_ID}/values/Sheet1%21A1%3AB2?valueInputOption=RAW");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${GOOGLE_ACCESS_TOKEN}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "range": "Sheet1!A1:B2",
  "majorDimension": "ROWS",
  "values": [
    [
      "项目",
      "状态"
    ],
    [
      "示例任务",
      "已同步"
    ]
  ]
};
const response = await fetch(url, {
  method: "PUT",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意，ID、文本和数字均为虚构，非接口实测结果。updatedCells 反映实际更新的单元格数；之后读取确认最终值。以下为结构示意，非本站实测结果。

{
  "spreadsheetId": "example_spreadsheet_id",
  "updatedRange": "Sheet1!A1:B2",
  "updatedRows": 2,
  "updatedColumns": 2,
  "updatedCells": 4
}

常见错误与排查

HTTP 401访问令牌缺失、无效或已过期。: 按本站授权场景使用 refresh_token 刷新；不要把 client_secret 或 API Key 当成 access_token。
HTTP 403权限不足、组织策略限制或达到用户配额。: 读取 error.details/reason；核对已授权 scope、文件共享权限和项目配额，不能只重复授权同一个 scope。
HTTP 429达到服务请求频率限制。: 采用带随机抖动的指数退避，限制重试次数，并减少批量轮询。
HTTP 400范围或数值结构无效。: 检查工作表名称、A1 表达式、valueInputOption 及二维数组。

调用注意

此接口只写单元格值，不负责颜色、边框或新建工作表；格式和结构要用 spreadsheets.batchUpdate。
授权范围覆盖整个电子表格文件，不能用 OAuth scope 只授权 A1:B2；需要应用端限制写入区域。

Sheets spreadsheets.values.update Sheets ValueRange 请求与响应

注意事项

核验日官方仍说明标准 API 使用无额外费用，同时公告 2026 年晚些时候计划对超配额用量计费；不把当前规则写成永久免费承诺。以项目配额及官方生效通知为准。
Sheets 当前读、写各为每项目每分钟 300 次、每用户每项目每分钟 60 次；429 需要退避。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
Google Web Server OAuth 2.0 授权码与刷新流程核验日期 2026-10-15
02
Sheets API 配额与费用核验日期 2026-10-15
03
Sheets spreadsheets.values.get核验日期 2026-10-15
04
Sheets ValueRange 请求与响应核验日期 2026-10-15
05
Sheets spreadsheets.values.update核验日期 2026-10-15

Google 文档与文件 API的其他调用手册

获取与刷新 Google 用户令牌列出可访问的 Drive 文件创建 Docs 文档并写入正文

← 返回Google 文档与文件 API的全部功能