Google Sheets技能使用说明

2026-03-26 新闻来源：网淘吧围观:70

电脑广告

手机广告

Google Sheets

通过托管的OAuth身份验证访问Google Sheets API。读取和写入电子表格数值、创建工作表、应用格式化以及执行批量操作。

快速开始

# 从电子表格读取数值（注意：范围是URL编码的）
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1%21A1%3AD10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/google-sheets/{native-api-path}

将{native-api-path}替换为实际的Google Sheets API端点路径。网关将请求代理到sheets.googleapis.com并自动注入您的OAuth令牌。

身份验证

所有请求都要求在Authorization头部中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

在以下网站登录或创建账户maton.ai
前往maton.ai/settings
复制您的API密钥

连接管理

在以下地址管理您的Google OAuth连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-sheets&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-sheets'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-sheets",
    "metadata": {}
  }
}

打开返回的url在浏览器中完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您连接了多个 Google 账户，请使用Maton-Connection标头来指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/SPREADSHEET_ID')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早）的活动连接。

API 参考

获取电子表格元数据

GET /google-sheets/v4/spreadsheets/{spreadsheetId}

获取数值

GET /google-sheets/v4/spreadsheets/{spreadsheetId}/values/{range}

示例：

GET /google-sheets/v4/spreadsheets/SHEET_ID/values/Sheet1%21A1%3AD10

获取多个范围

GET /google-sheets/v4/spreadsheets/{spreadsheetId}/values:batchGet?ranges=Sheet1%21A1%3AB10&ranges=Sheet2%21A1%3AC5

更新数值

PUT /google-sheets/v4/spreadsheets/{spreadsheetId}/values/{range}?valueInputOption=USER_ENTERED
Content-Type: application/json

{
  "values": [
    ["A1", "B1", "C1"],
    ["A2", "B2", "C2"]
  ]
}

追加数值

POST /google-sheets/v4/spreadsheets/{spreadsheetId}/values/{range}:append?valueInputOption=USER_ENTERED
Content-Type: application/json

{
  "values": [
    ["新行 1", "数据", "更多数据"],
    ["新行 2", "数据", "更多数据"]
  ]
}

批量更新数值

POST /google-sheets/v4/spreadsheets/{spreadsheetId}/values:batchUpdate
Content-Type: application/json

{
  "valueInputOption": "USER_ENTERED",
  "data": [
    {"range": "Sheet1!A1:B2", "values": [["A1", "B1"], ["A2", "B2"]]},
    {"range": "Sheet1!D1:E2", "values": [["D1", "E1"], ["D2", "E2"]]}
  ]
}

清除数值

POST /google-sheets/v4/spreadsheets/{spreadsheetId}/values/{range}:clear

创建电子表格

POST /google-sheets/v4/spreadsheets
Content-Type: application/json

{
  "properties": {"title": "新建电子表格"},
  "sheets": [{"properties": {"title": "Sheet1"}}]
}

批量更新（格式化、添加工作表等）

POST /google-sheets/v4/spreadsheets/{spreadsheetId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {"addSheet": {"properties": {"title": "新工作表"}}}
  ]
}

常见的 batchUpdate 请求

更新单元格并应用格式

{
  "updateCells": {
    "rows": [
      {"values": [{"userEnteredValue": {"stringValue": "姓名"}}, {"userEnteredValue": {"numberValue": 100}}]}
    ],
    "fields": "userEnteredValue",
    "start": {"sheetId": 0, "rowIndex": 0, "columnIndex": 0}
  }
}

格式化标题行（加粗 + 背景色）

{
  "repeatCell": {
    "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1, "startColumnIndex": 0, "endColumnIndex": 3},
    "cell": {
      "userEnteredFormat": {
        "backgroundColor": {"red": 0.2, "green": 0.6, "blue": 0.9},
        "textFormat": {"bold": true}
      }
    },
    "fields": "userEnteredFormat(backgroundColor,textFormat)"
  }
}

自动调整列宽

{
  "autoResizeDimensions": {
    "dimensions": {"sheetId": 0, "dimension": "COLUMNS", "startIndex": 0, "endIndex": 3}
  }
}

重命名工作表

{
  "updateSheetProperties": {
    "properties": {"sheetId": 0, "title": "新名称"},
    "fields": "title"
  }
}

插入行/列

{
  "insertDimension": {
    "range": {"sheetId": 0, "dimension": "ROWS", "startIndex": 1, "endIndex": 3},
    "inheritFromBefore": true
  }
}

排序范围

{
  "sortRange": {
    "range": {"sheetId": 0, "startRowIndex": 1, "endRowIndex": 10, "startColumnIndex": 0, "endColumnIndex": 3},
    "sortSpecs": [{"dimensionIndex": 1, "sortOrder": "DESCENDING"}]
  }
}

添加筛选器

{
  "setBasicFilter": {
    "filter": {
      "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 100, "startColumnIndex": 0, "endColumnIndex": 5}
    }
  }
}

删除工作表

{
  "deleteSheet": {"sheetId": 123456789}
}

数值输入选项

原始值- 数值按原样存储
用户输入- 数值按在用户界面中输入的方式解析（执行公式，解析数字）

范围表示法

Sheet1!A1:D10- 特定范围
Sheet1!A:D- 整个A到D列
Sheet1!1:10- 第1至10整行
工作表1- 整个工作表
A1:D10- 第一个工作表中的范围

代码示例

JavaScript

// 读取数值
const response = await fetch(
  'https://gateway.maton.ai/google-sheets/v4/spreadsheets/SHEET_ID/values/Sheet1!A1:D10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

// 写入数值
await fetch(
  'https://gateway.maton.ai/google-sheets/v4/spreadsheets/SHEET_ID/values/Sheet1!A1:B2?valueInputOption=USER_ENTERED',
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    },
    body: JSON.stringify({
      values: [['A1', 'B1'], ['A2', 'B2']]
    })
  }
);

Python

import os
import requests

# 读取数值
response = requests.get(
    'https://gateway.maton.ai/google-sheets/v4/spreadsheets/SHEET_ID/values/Sheet1!A1:D10',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

# 写入数值
response = requests.put(
    'https://gateway.maton.ai/google-sheets/v4/spreadsheets/SHEET_ID/values/Sheet1!A1:B2',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'valueInputOption': 'USER_ENTERED'},
    json={'values': [['A1', 'B1'], ['A2', 'B2']]}
)

注意事项

使用curl时，URL路径中的范围必须进行URL编码（! -> %21, : -> %3A）。JavaScript fetch和Python requests会自动处理编码。
使用valueInputOption=USER_ENTERED来解析公式和数字
通过Google Drive API删除电子表格，而非Sheets API
工作表ID为数字，可在电子表格元数据中找到
重要提示：使用curl命令时，如果URL包含方括号，请使用curl -g当URL包含括号时fields[],sort[],records[]) 以禁用通配符解析
重要提示：当将curl输出通过管道传递给jq或其他命令时，在某些shell环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开。通过管道传递时，您可能会遇到"无效API密钥"的错误。

错误处理

状态码	含义
400	缺少Google Sheets连接
401	无效或缺少Maton API密钥
429	请求频率受限（每个账户10次/秒）
4xx/5xx	来自Google Sheets API的透传错误

故障排除：API密钥问题

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证API密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

确保您的URL路径以google-sheets开头。例如：

正确：https://gateway.maton.ai/google-sheets/v4/spreadsheets/SPREADSHEET_ID
错误：https://gateway.maton.ai/v4/spreadsheets/SPREADSHEET_ID

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：File Search技能使用说明下一篇：Things Mac技能使用说明