Google Sheets API 使用指南：通过 cURL 读取、写入和管理电子表格数据

google-sheets by vm0-ai/vm0-skills

275 周安装量

48 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vm0-ai/vm0-skills --skill google-sheets

办公软件自动化数据处理 API

🇨🇳中文介绍

Google Sheets API

通过直接的 curl 调用使用 Google Sheets API 来读取、写入和管理电子表格数据。

官方文档：https://developers.google.com/sheets/api

使用场景

在以下情况下使用此技能：

读取数据 来自 Google Sheets
写入或更新 单元格值
追加行 到现有工作表
创建新的电子表格
获取电子表格元数据（工作表名称、属性）
批量更新 多个范围

占位符说明： {花括号} 中的值，如 {spreadsheet-id}，是占位符。执行时请将其替换为实际值。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 获取电子表格元数据

获取电子表格的信息（工作表、属性）：

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '{title: .properties.title, sheets: [.sheets[].properties | {sheetId, title}]}'

2. 读取单元格值

读取一个范围的单元格：

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A1:D10" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '.values'

3. 读取整个工作表

读取工作表中的所有数据：

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '.values'

4. 写入单元格值

更新一个范围的单元格。

写入 /tmp/gsheets_request.json：

{
  "values": [
    ["Name", "Email", "Status"]
  ]
}

curl -s -X PUT "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A1:C1?valueInputOption=USER_ENTERED" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.updatedCells'

valueInputOption 选项：

RAW：值按原样存储
USER_ENTERED：值按用户输入的方式解析（公式会被计算）

在工作表末尾添加新行。

写入 /tmp/gsheets_request.json：

{
  "values": [
    ["John Doe", "john@example.com", "Active"]
  ]
}

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A:C:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.updates | {updatedRange, updatedRows}'

6. 批量读取多个范围

在一次请求中读取多个范围：

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values:batchGet?ranges=Sheet1%21A1:B5&ranges=Sheet1%21D1:E5" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '.valueRanges'

7. 批量更新多个范围

在一次请求中更新多个范围。

写入 /tmp/gsheets_request.json：

{
  "valueInputOption": "USER_ENTERED",
  "data": [
    {
      "range": "Sheet1!A1",
      "values": [["Header 1"]]
    },
    {
      "range": "Sheet1!B1",
      "values": [["Header 2"]]
    }
  ]
}

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values:batchUpdate" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.totalUpdatedCells'

8. 清除单元格值

清除一个范围的单元格。

写入 /tmp/gsheets_request.json：

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A2:C100:clear" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.clearedRange'

9. 创建新的电子表格

写入 /tmp/gsheets_request.json：

{
  "properties": {
    "title": "My New Spreadsheet"
  },
  "sheets": [
    {
      "properties": {
        "title": "Data"
      }
    }
  ]
}

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '{spreadsheetId, spreadsheetUrl}'

10. 添加新工作表

向现有电子表格添加新工作表。

写入 /tmp/gsheets_request.json：

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "New Sheet"
        }
      }
    }
  ]
}

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}:batchUpdate" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.replies[0].addSheet.properties'

从电子表格中删除一个工作表（使用元数据中的 sheetId）。

写入 /tmp/gsheets_request.json：

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": 123456789
      }
    }
  ]
}

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}:batchUpdate" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json

查找包含特定文本的单元格（读取所有数据然后过滤）：

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '[.values[] | select(.[0] | ascii_downcase | contains("search_term"))]'

表示法	描述
`Sheet1!A1`	Sheet1 中的单个单元格 A1
`Sheet1!A1:B2`	从 A1 到 B2 的范围
`Sheet1!A:A`	整个 A 列
`Sheet1!1:1`	整个第 1 行
`Sheet1!A1:C`	从 A1 到 C 列末尾
`'Sheet Name'!A1`	包含空格的工作表名称需要引号

速率限制：默认配额为每个项目每分钟 300 个请求
使用批量操作：合并多个读取/写入操作以减少 API 调用
valueInputOption：对于公式使用 USER_ENTERED，对于字面字符串使用 RAW
URL 编码范围：范围中的工作表名称分隔符在 URL 中必须编码为 %21（例如，Sheet1%21A1:D10）

2026 年 1 月 24 日

🇺🇸English

Google Sheets API

Use the Google Sheets API via direct curl calls to read, write, and manage spreadsheet data.

Official docs: https://developers.google.com/sheets/api

When to Use

Use this skill when you need to:

Read data from Google Sheets
Write or update cell values
Append rows to existing sheets
Create new spreadsheets
Get spreadsheet metadata (sheet names, properties)
Batch update multiple ranges at once

Placeholders: Values in {curly-braces} like {spreadsheet-id} are placeholders. Replace them with actual values when executing.

Important: In range notation, the sheet-name separator ! must be URL encoded as %21 in the URL path. For example, Sheet1!A1:D10 becomes Sheet1%21A1:D10. All examples below use this encoding.

How to Use

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

Finding your Spreadsheet ID: The spreadsheet ID is in the URL: https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID}/edit

1. Get Spreadsheet Metadata

Get information about a spreadsheet (sheets, properties):

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '{title: .properties.title, sheets: [.sheets[].properties | {sheetId, title}]}'

2. Read Cell Values

Read a range of cells:

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A1:D10" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '.values'

3. Read Entire Sheet

Read all data from a sheet:

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '.values'

4. Write Cell Values

Update a range of cells.

Write to /tmp/gsheets_request.json:

{
  "values": [
    ["Name", "Email", "Status"]
  ]
}

Then run:

curl -s -X PUT "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A1:C1?valueInputOption=USER_ENTERED" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.updatedCells'

valueInputOption:

RAW: Values are stored as-is
USER_ENTERED: Values are parsed as if typed by user (formulas evaluated)

5. Append Rows

Add new rows to the end of a sheet.

Write to /tmp/gsheets_request.json:

{
  "values": [
    ["John Doe", "john@example.com", "Active"]
  ]
}

Then run:

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A:C:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.updates | {updatedRange, updatedRows}'

6. Batch Read Multiple Ranges

Read multiple ranges in one request:

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values:batchGet?ranges=Sheet1%21A1:B5&ranges=Sheet1%21D1:E5" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '.valueRanges'

7. Batch Update Multiple Ranges

Update multiple ranges in one request.

Write to /tmp/gsheets_request.json:

{
  "valueInputOption": "USER_ENTERED",
  "data": [
    {
      "range": "Sheet1!A1",
      "values": [["Header 1"]]
    },
    {
      "range": "Sheet1!B1",
      "values": [["Header 2"]]
    }
  ]
}

Then run:

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values:batchUpdate" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.totalUpdatedCells'

8. Clear Cell Values

Clear a range of cells.

Write to /tmp/gsheets_request.json:

{}

Then run:

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1%21A2:C100:clear" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.clearedRange'

9. Create New Spreadsheet

Write to /tmp/gsheets_request.json:

{
  "properties": {
    "title": "My New Spreadsheet"
  },
  "sheets": [
    {
      "properties": {
        "title": "Data"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '{spreadsheetId, spreadsheetUrl}'

10. Add New Sheet

Add a new sheet to an existing spreadsheet.

Write to /tmp/gsheets_request.json:

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "New Sheet"
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}:batchUpdate" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json | jq '.replies[0].addSheet.properties'

11. Delete Sheet

Delete a sheet from a spreadsheet (use sheetId from metadata).

Write to /tmp/gsheets_request.json:

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": 123456789
      }
    }
  ]
}

Then run:

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}:batchUpdate" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gsheets_request.json

12. Search for Values

Find cells containing specific text (read all then filter):

curl -s "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet-id}/values/Sheet1" --header "Authorization: Bearer $(printenv GOOGLE_SHEETS_TOKEN)" | jq '[.values[] | select(.[0] | ascii_downcase | contains("search_term"))]'

A1 Notation Reference

Notation	Description
`Sheet1!A1`	Single cell A1 in Sheet1
`Sheet1!A1:B2`	Range from A1 to B2
`Sheet1!A:A`	Entire column A
`Sheet1!1:1`	Entire row 1
`Sheet1!A1:C`	From A1 to end of column C
`'Sheet Name'!A1`	Sheet names with spaces need quotes

Guidelines

Rate limits : Default quota is 300 requests per minute per project
Use batch operations : Combine multiple reads/writes to reduce API calls
valueInputOption : Use USER_ENTERED for formulas, RAW for literal strings
URL encode ranges : The sheet-name separator in ranges must be encoded as %21 in URLs (e.g., Sheet1%21A1:D10)

Weekly Installs

275

Repository

vm0-ai/vm0-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex251

opencode249

gemini-cli245

github-copilot233

claude-code205

cursor203

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

27,400 周安装

Google Sheets API 使用指南：通过 cURL 读取、写入和管理电子表格数据

🇨🇳中文介绍

Google Sheets API

使用场景

相关 Skills

使用方法

1. 获取电子表格元数据

2. 读取单元格值

3. 读取整个工作表

4. 写入单元格值

5. 追加行

6. 批量读取多个范围

7. 批量更新多个范围

8. 清除单元格值

9. 创建新的电子表格

10. 添加新工作表

11. 删除工作表

12. 搜索值

A1 表示法参考

指南

🇺🇸English

Google Sheets API

When to Use

How to Use

1. Get Spreadsheet Metadata

2. Read Cell Values

3. Read Entire Sheet

4. Write Cell Values

5. Append Rows

6. Batch Read Multiple Ranges

7. Batch Update Multiple Ranges

8. Clear Cell Values

9. Create New Spreadsheet

10. Add New Sheet

11. Delete Sheet

12. Search for Values

A1 Notation Reference

Guidelines

最新 Skills