Google Drive

通过托管的 OAuth 认证访问 Google Drive API。列出、搜索、创建和管理文件与文件夹。

快速开始

# 列出文件
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-drive/drive/v3/files?pageSize=10')
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-drive/{native-api-path}

将{native-api-path}替换为实际的 Google Drive API 端点路径。网关将请求代理到www.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-drive&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-drive'}).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-drive",
    "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 Drive 连接，请使用Maton-Connection标头指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-drive/drive/v3/files?pageSize=10')
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-drive/drive/v3/files?pageSize=10

带查询条件：

GET /google-drive/drive/v3/files?q=name%20contains%20'report'&pageSize=10

仅文件夹：

获取 /google-drive/drive/v3/files?q=mimeType='application/vnd.google-apps.folder'

特定文件夹中的文件：

获取 /google-drive/drive/v3/files?q='文件夹ID'+in+parents

包含字段：

获取 /google-drive/drive/v3/files?fields=files(id,name,mimeType,createdTime,modifiedTime,size)

获取文件元数据

获取 /google-drive/drive/v3/files/{文件ID}?fields=id,name,mimeType,size,createdTime

下载文件内容

获取 /google-drive/drive/v3/files/{文件ID}?alt=media

导出 Google 文档

获取 /google-drive/drive/v3/files/{文件ID}/export?mimeType=application/pdf

创建文件（仅元数据）

发布 /google-drive/drive/v3/files
内容类型：application/json

{
  "name": "新文档",
  "mimeType": "application/vnd.google-apps.document"
}

创建文件夹

发布 /google-drive/drive/v3/files
内容类型：application/json

{
  "name": "新建文件夹",
  "mimeType": "application/vnd.google-apps.folder"
}

更新文件元数据

补丁 /google-drive/drive/v3/files/{文件ID}
内容类型：application/json

{
  "name": "重命名文件"
}

将文件移动到文件夹

PATCH /google-drive/drive/v3/files/{fileId}?addParents=新文件夹ID&removeParents=旧文件夹ID

删除文件

DELETE /google-drive/drive/v3/files/{fileId}

复制文件

POST /google-drive/drive/v3/files/{fileId}/copy
Content-Type: application/json

{
  "name": "文件副本"
}

文件上传

根据文件大小以及是否需要包含元数据，Google Drive 支持三种上传类型。

简单上传（媒体上传）

适用于不超过 5MB 且无需设置元数据的文件。

POST /google-drive/upload/drive/v3/files?uploadType=media
Content-Type: text/plain

<文件内容>

Python 示例：

import urllib.request, os

file_content = b'Hello, this is file content!'

url = 'https://gateway.maton.ai/google-drive/upload/drive/v3/files?uploadType=media'
req = urllib.request.Request(url, data=file_content, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'text/plain')
response = urllib.request.urlopen(req)

多部分上传

适用于不超过 5MB 且需要包含元数据（名称、描述等）的文件。

POST /google-drive/upload/drive/v3/files?uploadType=multipart
Content-Type: multipart/related; boundary=boundary

--boundary
Content-Type: application/json; charset=UTF-8

{"name": "myfile.txt", "description": "My file"}
--boundary
Content-Type: text/plain

<文件内容>
--boundary--

Python 示例：

import urllib.request, os, json

boundary = '----Boundary'
metadata = json.dumps({'name': 'myfile.txt', 'description': 'My file'})
file_content = 'File content here'

body = f'''--{boundary}\r
Content-Type: application/json; charset=UTF-8\r
\r
{metadata}\r
--{boundary}\r
Content-Type: text/plain\r
\r
{file_content}\r
--{boundary}--'''.encode()

url = 'https://gateway.maton.ai/google-drive/upload/drive/v3/files?uploadType=multipart'
req = urllib.request.Request(url, data=body, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', f'multipart/related; boundary={boundary}')
response = urllib.request.urlopen(req)

可恢复上传（大文件）

适用于大文件（建议文件大小 > 5MB）。此方法：

1. 初始化会话 - 获取上传 URI
2. 分块上传 - 分段发送文件
3. 支持断点续传 - 如果中断，可以从断点处继续上传

步骤 1：初始化上传会话

POST /google-drive/upload/drive/v3/files?uploadType=resumable
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: application/octet-stream
X-Upload-Content-Length: <文件大小>

{"name": "large_file.bin"}

响应包含Location标头，其中包含上传 URI。

步骤 2：上传内容

PUT <upload_uri>
Content-Length: <文件大小>
Content-Type: application/octet-stream

<文件内容>

Python 示例（完整）：

import urllib.request, os, json

file_path = '/path/to/large_file.bin'
file_size = os.path.getsize(file_path)

# 步骤 1：初始化可恢复的上传会话
url = 'https://gateway.maton.ai/google-drive/upload/drive/v3/files?uploadType=resumable'
metadata = json.dumps({'name': 'large_file.bin'}).encode()

req = urllib.request.Request(url, data=metadata, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json; charset=UTF-8')
req.add_header('X-Upload-Content-Type', 'application/octet-stream')
req.add_header('X-Upload-Content-Length', str(file_size))

response = urllib.request.urlopen(req)
upload_uri = response.headers['Location']

# 步骤 2：分块上传文件（例如，5MB 的块）
chunk_size = 5 * 1024 * 1024
with open(file_path, 'rb') as f:
    offset = 0
    while offset < file_size:
        chunk = f.read(chunk_size)
        end = offset + len(chunk) - 1

        req = urllib.request.Request(upload_uri, data=chunk, method='PUT')
        req.add_header('Content-Length', str(len(chunk)))
        req.add_header('Content-Range', f'bytes {offset}-{end}/{file_size}')

        response = urllib.request.urlopen(req)
        offset += len(chunk)

result = json.load(response)
print(f"已上传: {result['id']}")

恢复中断的上传：

如果上传中断，查询上传 URI 以获取当前状态：

req = urllib.request.Request(upload_uri, method='PUT')
req.add_header('Content-Length', '0')
req.add_header('Content-Range', 'bytes */*')
response = urllib.request.urlopen(req)
# 检查响应中的 Range 标头以获取当前偏移量

更新文件内容

要更新现有文件的内容：

PATCH /google-drive/upload/drive/v3/files/{fileId}?uploadType=media
Content-Type: text/plain

<新文件内容>

Python 示例：

import urllib.request, os

file_id = '你的文件ID'
new_content = b'更新后的文件内容！'

url = f'https://gateway.maton.ai/google-drive/upload/drive/v3/files/{file_id}?uploadType=media'
req = urllib.request.Request(url, data=new_content, method='PATCH')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'text/plain')
response = urllib.request.urlopen(req)

上传到特定文件夹

在元数据中包含文件夹ID：

metadata = json.dumps({
    'name': 'myfile.txt',
    'parents': ['文件夹ID']
})

分享文件

POST /google-drive/drive/v3/files/{fileId}/permissions
Content-Type: application/json

{
  "role": "reader",
  "type": "user",
  "emailAddress": "user@example.com"
}

查询操作符

在q参数中使用：

• name = '精确名称'
• name contains '部分'
• mimeType = 'application/pdf'
• 'folderId' in parents
• trashed = false
• modifiedTime > '2024-01-01T00:00:00'

使用and组合：

name contains 'report' and mimeType = 'application/pdf'

常见 MIME 类型

• application/vnd.google-apps.document- Google 文档
• application/vnd.google-apps.spreadsheet- Google 表格
• application/vnd.google-apps.presentation- Google 幻灯片
• application/vnd.google-apps.folder- 文件夹
• application/pdf- PDF

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/google-drive/drive/v3/files?pageSize=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/google-drive/drive/v3/files',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'pageSize': 10}
)

注释

• 使用fields参数来限制响应数据
• 分页使用pageToken来自先前响应的nextPageToken
• 导出功能仅适用于 Google Workspace 文件
• 上传类型：使用uploadType=media进行简单上传（最大 5MB），uploadType=multipart用于包含元数据的上传（最大 5MB），uploadType=resumable用于大文件（推荐用于 > 5MB 的文件）
• 上传端点：文件上传使用/upload/drive/v3/files（请注意/upload前缀）
• 可恢复上传：对于大文件，请使用支持分块传输的可恢复上传（最小分块大小为 256KB，推荐 5MB）
• 最大文件大小：Google Drive 支持最大 5TB 的文件
• 重要提示：使用 curl 命令时，如果 URL 包含方括号（fields[]、sort[]、records[]），请使用curl -g以禁用通配符解析
• 重要提示：当将 curl 输出通过管道传递给jq或其他命令时，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开。通过管道传输时，您可能会遇到"无效API密钥"错误。

错误处理

故障排除：API密钥问题

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

echo $MATON_API_KEY

2. 通过列出连接来验证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-drive开头。例如：

• 正确示例：https://gateway.maton.ai/google-drive/drive/v3/files
• 错误示例：https://gateway.maton.ai/drive/v3/files

资源

• Drive API 概览
• 列出文件
• 获取文件
• 创建文件
• 更新文件
• 删除文件
• 导出文件
• 上传文件
• 可恢复上传
• 搜索查询语法
• Maton 社区
• Maton 技术支持