Google Docs

通过受管 OAuth 认证访问 Google Docs API。支持创建文档、插入与格式化文本，以及管理文档内容。

快速开始

CLI：

maton google-docs document view DOC_ID

maton api '/google-docs/v1/documents/{documentId}'

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/{documentId}')
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://api.maton.ai/google-docs/{native-api-path}

Maton 将请求代理至 docs.googleapis.com，并自动注入您的 OAuth Token。

安装

NPM：

npm install -g @maton/cli

Homebrew：

brew install maton-ai/cli/maton

认证

CLI：

maton login                          # 打开浏览器获取 API 密钥
maton login --interactive            # 跳过浏览器，直接粘贴 API 密钥
maton whoami                         # 显示当前认证状态

手动配置：

1. 在 maton.ai 登录或注册账户
2. 访问 maton.ai/settings
3. 复制您的 API 密钥
4. 将 API 密钥设为环境变量 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

连接管理

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

列出连接

CLI：

maton connection list google-docs --status ACTIVE

maton api -X GET /connections -f app=google-docs -f status=ACTIVE

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-docs&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

创建连接

CLI：

maton connection create google-docs

maton api /connections -f app=google-docs

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).encode()
req = urllib.request.Request('https://api.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

获取连接

CLI：

maton connection view {connection_id}

maton api /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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": "{connection_id}",
    "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-docs",
    "metadata": {}
  }
}

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

删除连接

CLI：

maton connection delete {connection_id}

maton api -X DELETE /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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 Docs 连接，请显式指定要使用的连接：

CLI：

maton google-docs document view DOC_ID --connection {connection_id}

maton api /google-docs/v1/documents/{documentId} --connection {connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/{documentId}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

若存在多个连接，务必始终指定连接，以确保请求路由至目标账户。

安全与权限

• 访问范围限定于已连接 Google Docs 账户内的文档、内容、格式及文档元数据。
• 所有写入操作均需用户显式授权。 在执行任何创建（create）、更新（update）或删除（delete）调用前，必须向用户确认目标资源及其预期影响。

API 参考

获取文档

GET /google-docs/v1/documents/{documentId}

示例：

maton google-docs document view DOC_ID            # 人类可读摘要（ID、标题、修订版本）
maton google-docs document view DOC_ID --json     # 完整文档载荷（正文、样式等）

创建文档

POST /google-docs/v1/documents
Content-Type: application/json

{
  "title": "New Document"
}

示例：

maton google-docs document create --title 'New Document'

批量更新文档

POST /google-docs/v1/documents/{documentId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "insertText": {
        "location": {"index": 1},
        "text": "Hello, World!"
      }
    }
  ]
}

示例：

maton google-docs document write DOC_ID --text 'Hello, World!'

常用 batchUpdate 请求类型

插入文本

{
  "insertText": {
    "location": {"index": 1},
    "text": "Text to insert"
  }
}

删除内容

{
  "deleteContentRange": {
    "range": {
      "startIndex": 1,
      "endIndex": 10
    }
  }
}

替换全部文本

{
  "replaceAllText": {
    "containsText": {
      "text": "{{placeholder}}",
      "matchCase": true
    },
    "replaceText": "replacement value"
  }
}

插入表格

{
  "insertTable": {
    "location": {"index": 1},
    "rows": 3,
    "columns": 3
  }
}

更新文本样式

{
  "updateTextStyle": {
    "range": {
      "startIndex": 1,
      "endIndex": 10
    },
    "textStyle": {
      "bold": true,
      "fontSize": {"magnitude": 14, "unit": "PT"}
    },
    "fields": "bold,fontSize"
  }
}

插入分页符

{
  "insertPageBreak": {
    "location": {"index": 1}
  }
}

代码示例

CLI

# 创建新文档
maton google-docs document create --title 'Sprint notes'

# 查看文档
maton google-docs document view DOC_ID

# 向文档写入文本
maton google-docs document write DOC_ID --text 'Hello!'

JavaScript

// 创建文档
const response = await fetch(
  'https://api.maton.ai/google-docs/v1/documents',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    },
    body: JSON.stringify({ title: 'New Document' })
  }
);

// 插入文本
await fetch(
  `https://api.maton.ai/google-docs/v1/documents/${docId}:batchUpdate`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    },
    body: JSON.stringify({
      requests: [{ insertText: { location: { index: 1 }, text: 'Hello!' } }]
    })
  }
);

Python

import os
import requests

# 创建文档
response = requests.post(
    'https://api.maton.ai/google-docs/v1/documents',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'title': 'New Document'}
)

注意事项

• 索引位置为 1-based（文档起始索引为 1）
• 使用 endOfSegmentLocation 在末尾追加内容
• batchUpdate 中的多个请求将原子性地应用
• 建议先调用 Get Document 获取准确索引，再执行更新操作
• 样式更新中的 fields 参数采用字段掩码（field mask）语法
• 重要：使用 curl 命令时，若 URL 中含方括号（如 fields[]、sort[]、records[]），请添加 curl -g 参数禁用 glob 解析
• 重要：当将 curl 输出管道传输至 jq 或其他命令时，在部分 Shell 环境下环境变量（如 $MATON_API_KEY）可能无法正确展开，导致“Invalid API key”错误

错误处理

故障排查：API 密钥问题

CLI：

1. 检查当前认证状态：

maton whoami

2. 通过列出连接验证 API 密钥有效性：

maton connection list

手动验证：

1. 确认 MATON_API_KEY 环境变量已设置：

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

故障排查：应用名称无效

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

• 正确：https://api.maton.ai/google-docs/v1/documents/{documentId}
• 错误：https://api.maton.ai/docs/v1/documents/{documentId}

相关资源

• Docs API 概览
• 获取文档
• 创建文档
• 批量更新
• 请求类型
• 文档结构
• Maton CLI 手册
• Maton 社区
• Maton 支持