基础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 $MATONAPIKEY

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

bash
export MATONAPIKEY=YOURAPIKEY

获取您的API密钥

1. 1. 在maton.ai登录或创建账户
2. 前往maton.ai/settings
3. 复制您的API密钥

连接管理

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

列出连接

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

创建连接

bash
python < 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.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id})
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

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

删除连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id}, method=DELETE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

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

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

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

API参考

获取电子表格元数据

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

获取值

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

示例：

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

获取多个范围

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

更新值

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

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

追加值

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

{
values: [
[New Row 1, Data, More Data],
[New Row 2, Data, More Data]
]
}

批量更新值

bash
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]]}
]
}

清除值

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

创建电子表格

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

{
properties: {title: New Spreadsheet},
sheets: [{properties: {title: Sheet1}}]
}

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

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

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

常用batchUpdate请求

更新带格式的单元格

json
{
updateCells: {
rows: [
{values: [{userEnteredValue: {stringValue: Name}}, {userEnteredValue: {numberValue: 100}}]}
],
fields: userEnteredValue,
start: {sheetId: 0, rowIndex: 0, columnIndex: 0}
}
}

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

json
{
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)
}
}

自动调整列宽

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

重命名工作表

json
{
updateSheetProperties: {
properties: {sheetId: 0, title: NewName},
fields: title
}
}

插入行/列

json
{
insertDimension: {
range: {sheetId: 0,