Google 文档

通过托管的 OAuth 认证访问 Google Docs API。创建文档，插入和格式化文本，以及管理文档内容。

快速开始

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

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

认证

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

Authorization: Bearer $MATON_API_KEY

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

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或在maton.ai
2. 创建账户前往
3. maton.ai/settings

复制您的 API 密钥

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

列出连接

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

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).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-docs",
    "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 Docs 连接，请使用Maton-Connection头来指定要使用哪一个：

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

创建文档

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

{
  "title": "New Document"
}

批量更新文档

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

{
  "requests": [
    {
      "insertText": {
        "location": {"index": 1},
        "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}
  }
}

代码示例

JavaScript

// Create document
const response = await fetch(
  'https://gateway.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' })
  }
);

// Insert text
await fetch(
  `https://gateway.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

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

注意事项

• 索引位置基于1开始计数（文档起始索引为1）
• 使用endOfSegmentLocation在末尾追加内容
• batchUpdate中的多个请求以原子方式应用
• 更新前先获取文档以找到正确的索引位置
• 样式更新中的fields参数使用字段掩码语法
• 重要提示：使用curl命令时，如果URL包含方括号（curl -g请使用此参数fields[]、sort[]等）records[]) 以禁用通配符解析
• 重要提示：当通过管道将curl输出传递给jq或其他命令时，在某些shell环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开。通过管道传递时，您可能会遇到"无效的API密钥"错误。

错误处理

故障排除：API密钥问题

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

echo $MATON_API_KEY

1. 通过列出连接来验证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

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

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

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

资源

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