文档

Google Sheets

试用

通过托管 OAuth 的统一网关读写 Google Sheets 数据。

它能做什么

提供对 Google Sheets 的 HTTP 接口访问，支持读取单元格值、写入数据、追加行以及批量更新。覆盖单元格格式化、新建工作表、自动调整列宽、排序与筛选等能力。认证采用 Bearer 令牌配合托管的 OAuth 连接，每个电子表格 ID 会绑定到用户已授权的 Google 账号。文档附带 JavaScript 与 Python 示例，并支持 RAW 和 USER_ENTERED 两种值输入模式。

什么时候用它

  • 把表格指定区间读入应用
  • 更新或向 Google 表格追加行
  • 通过 batchUpdate 设置格式或新增工作表
  • 同时挂载多个 Google 账号分别操作表格

技能文档

Google Sheets

Access the Google Sheets API with managed OAuth authentication. Read and write spreadsheet values, create sheets, apply formatting, and perform batch operations.

Quick Start

# Read values from a spreadsheet
curl -s -X GET 'https://gateway.maton.ai/google-sheets/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Base URL

https://gateway.maton.ai/google-sheets/v4/spreadsheets/{spreadsheetId}/{endpoint}

The gateway proxies requests to sheets.googleapis.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

  1. Sign in at maton.ai
  2. Go to maton.ai/settings
  3. Copy your API key

Connection Management

Manage your Google OAuth connections at https://ctrl.maton.ai.

List Connections

curl -s -X GET 'https://ctrl.maton.ai/connections?app=google-sheets&status=ACTIVE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create Connection

curl -s -X POST 'https://ctrl.maton.ai/connections' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"app": "google-sheets"}'

Get Connection

curl -s -X GET 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-sheets"
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

curl -s -X DELETE 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Using Multiple Connections

If you have multiple Google accounts connected, specify which to use:

curl -s -X GET 'https://gateway.maton.ai/google-sheets/v4/spreadsheets/SPREADSHEET_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Maton-Connection: {connection_id}'

API Reference

Get Spreadsheet Metadata

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

Get Values

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

Example:

GET /google-sheets/v4/spreadsheets/SHEET_ID/values/Sheet1!A1:D10

Get Multiple Ranges

GET /google-sheets/v4/spreadsheets/{spreadsheetId}/values:batchGet?ranges=Sheet1!A1:B10&ranges=Sheet2!A1:C5

Update Values

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

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

Append Values

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

Batch Update Values

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

Clear Values

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

Create Spreadsheet

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

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

Batch Update (formatting, add sheets, etc.)

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

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

Common batchUpdate Requests

Update Cells with Formatting

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

Format Header Row (Bold + Background Color)

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

Auto-Resize Columns

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

Rename Sheet

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

Insert Rows/Columns

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

Sort Range

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

Add Filter

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

Delete Sheet

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

Value Input Options

  • RAW - Values are stored as-is
  • USER_ENTERED - Values are parsed as if typed into the UI (formulas executed, numbers parsed)

Range Notation

  • Sheet1!A1:D10 - Specific range
  • Sheet1!A:D - Entire columns A through D
  • Sheet1!1:10 - Entire rows 1 through 10
  • Sheet1 - Entire sheet
  • A1:D10 - Range in first sheet

Code Examples

JavaScript

// Read values
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}`
    }
  }
);

// Write values
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

# Read values
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"]}'}
)

# Write values
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']]}
)

Notes

  • Range in URL path must be URL-encoded (! → %21, : → %3A)
  • Use valueInputOption=USER_ENTERED to parse formulas and numbers
  • Delete spreadsheets via the Google Drive API, not Sheets API
  • Sheet IDs are numeric and found in the spreadsheet metadata

Error Handling

StatusMeaning
400Missing Google Sheets connection
401Invalid or missing Maton API key
429Rate limited (10 req/sec per account)
4xx/5xxPassthrough error from Google Sheets API

Resources

常见问题

认证是如何完成的？
请求在 Authorization 头中携带 Bearer 令牌（MATON_API_KEY），网关会代为转发到 sheets.googleapis.com 并注入对应 Google 账号的 OAuth 令牌。
能直接删除整个电子表格吗？
不能。文档明确指出删除电子表格需要走 Google Drive API，而不是 Sheets API。
接口的速率限制是多少？
网关按账号限制为每秒 10 次请求，超出会返回 HTTP 429。

相关技能

Google Sheets via gog

Use this skill when you need to create, inspect, update, append to, or reorganize Google Sheets from a locally installed `gog` CLI. It is for local Google ac...

24 次安装

google-docs-connector

Google Docs Connector: Google Docs: create, edit, format documents. Tables, images, headers, page breaks. Export to PDF/DOCX/HTML. Share and manage permissions. Use when an agent needs google docs connector, document automation, report generation, template creation, collaborative editing, batch update, document id, requests through AgentPMT-hosted remote tool calls. Discovery terms: google docs connector, document automation, report generation, template creation, collaborative editing.

1 次安装

Google Drive

通过托管 OAuth，让代理安全访问 Google Drive 进行文件和文件夹操作。

作者 byungkyu

Google Slides

通过托管 OAuth 代理，使用 Slides API 创建和管理 Google Slides 演示文稿。

作者 byungkyu1 次安装

Google Workspace Automation

Design Gmail, Drive, Sheets, and Calendar automations with scope-aware plans. Use for repeatable daily task automation with explicit OAuth scopes and audit-r...

56 次安装1 星标

plaud-recordings-to-google-drive-sync

Plaud Recordings to Google Drive Sync: Automatically backs up your Plaud recordings to Google Drive and keeps a tracking spreadsheet in Google Sheets. Each time you run this workflow, it downloads any new recordings from your Plaud account to a "Plaud Recordings" folder in Drive, creates a transcript for each recording (using Plaud's built-in transcripts when available, or automatic speech-to-text otherwise), saves the transcript alongside the audio file, identifies what each recording is about.

byungkyu 的更多技能

浏览全部技能

Twilio

通过 OAuth 代理调用 Twilio API,完成短信发送、语音外呼与电话号资源管理。

作者 byungkyu173 次安装8 星标

Google Drive

通过托管 OAuth，让代理安全访问 Google Drive 进行文件和文件夹操作。

作者 byungkyu

Google Meet

通过托管 OAuth 管理 Google Meet 会议空间、参会者、会议记录、录制和转写稿。

作者 byungkyu

Outlook Api

通过 Microsoft Graph 接入 Outlook，读取、发送、管理邮件、文件夹、日历事件和联系人，OAuth 由平台托管。

作者 byungkyu

Google Slides

通过托管 OAuth 代理，使用 Slides API 创建和管理 Google Slides 演示文稿。

作者 byungkyu1 次安装

Api Gateway

通过托管网关调用第三方 API,免去自行管理 OAuth 和密钥的负担。

作者 byungkyu