Dropbox技能使用说明
2026-03-28
新闻来源：网淘吧
围观:17
电脑广告
手机广告
Dropbox
通过托管式 OAuth 认证访问 Dropbox API。管理文件和文件夹、搜索内容、检索元数据以及处理文件版本。
快速入门
# List files in root folder
python <<'EOF'
import urllib.request, os, json
data = json.dumps({"path": ""}).encode()
req = urllib.request.Request('https://gateway.maton.ai/dropbox/2/files/list_folder', 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
基础 URL
https://gateway.maton.ai/dropbox/2/{endpoint}
网关将请求代理至api.dropboxapi.com并自动注入您的 OAuth 令牌。
重要提示：Dropbox API v2 对所有端点使用 POST 方法，请求体为 JSON 格式。
认证
所有请求均需在 Authorization 头部包含 Maton API 密钥：
Authorization: Bearer $MATON_API_KEY
环境变量：将您的 API 密钥设置为MATON_API_KEY：
export MATON_API_KEY="YOUR_API_KEY"
获取您的 API 密钥
复制您的 API 密钥
请在以下网址管理您的Dropbox OAuth连接https://ctrl.maton.ai。
列出连接
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=dropbox&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': 'dropbox'}).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": "1efbb655-88e9-4a23-ad3b-f3e19cbff279",
"status": "ACTIVE",
"creation_time": "2026-02-09T23:34:49.818074Z",
"last_updated_time": "2026-02-09T23:37:09.697559Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "dropbox",
"metadata": {}
}
}
在浏览器中打开返回的网址以完成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
指定连接
如果您有多个Dropbox连接，请使用Maton-Connection标头指定要使用的连接：
python <<'EOF'
import urllib.request, os, json
data = json.dumps({"path": ""}).encode()
req = urllib.request.Request('https://gateway.maton.ai/dropbox/2/files/list_folder', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '1efbb655-88e9-4a23-ad3b-f3e19cbff279')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
如果省略，网关将使用默认（最早创建的）活动连接。
API参考
用户
获取当前账户
POST /dropbox/2/users/get_current_account
Content-Type: application/json
null
响应：
{
"account_id": "dbid:AAA-AdT84WzkyLw5s590DbYF1nGomiAoO8I",
"name": {
"given_name": "John",
"surname": "Doe",
"familiar_name": "John",
"display_name": "John Doe",
"abbreviated_name": "JD"
},
"email": "john@example.com",
"email_verified": true,
"disabled": false,
"country": "US",
"locale": "en",
"account_type": {
".tag": "basic"
},
"root_info": {
".tag": "user",
"root_namespace_id": "11989877987",
"home_namespace_id": "11989877987"
}
}
获取空间使用情况
POST /dropbox/2/users/get_space_usage
Content-Type: application/json
null
响应：
{
"used": 538371,
"allocation": {
".tag": "individual",
"allocated": 2147483648
}
}
文件和文件夹
列出文件夹
POST /dropbox/2/files/list_folder
Content-Type: application/json
{
"path": "",
"recursive": false,
"include_deleted": false,
"include_has_explicit_shared_members": false
}
使用空字符串""表示根文件夹。
可选参数：
recursive（递归）- 包含子目录内容（默认值：false）include_deleted（包含已删除文件）- 包含已删除文件（默认值：false）include_media_info（包含媒体信息）- 包含照片/视频的媒体信息limit（限制）- 每次响应的最大条目数（1-2000）
响应：
{
"entries": [
{
".tag": "file",
"name": "document.pdf",
"path_lower": "/document.pdf",
"path_display": "/document.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAABQ",
"client_modified": "2026-02-09T19:58:12Z",
"server_modified": "2026-02-09T19:58:13Z",
"rev": "016311c063b4f8700000002caa704e3",
"size": 538371,
"is_downloadable": true,
"content_hash": "6542845d7b65ffc5358ebaa6981d991bab9fda194afa48bd727fcbe9e4a3158b"
},
{
".tag": "folder",
"name": "Documents",
"path_lower": "/documents",
"path_display": "/Documents",
"id": "id:Awe3Av8A8YYAAAAAAAAABw"
}
],
"cursor": "AAVqv-MUYFlM98b1QpFK6YaYC8L1s39lWjqbeqgWu4un...",
"has_more": false
}
继续列出文件夹
POST /dropbox/2/files/list_folder/continue
Content-Type: application/json
{
"cursor": "AAVqv-MUYFlM98b1QpFK6YaYC8L1s39lWjqbeqgWu4un..."
}
当has_more（还有更多）在前一次响应中为真时使用。
获取元数据
POST /dropbox/2/files/get_metadata
Content-Type: application/json
{
"path": "/document.pdf",
"include_media_info": false,
"include_deleted": false,
"include_has_explicit_shared_members": false
}
响应：
{
".tag": "file",
"name": "document.pdf",
"path_lower": "/document.pdf",
"path_display": "/document.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAABQ",
"client_modified": "2026-02-09T19:58:12Z",
"server_modified": "2026-02-09T19:58:13Z",
"rev": "016311c063b4f8700000002caa704e3",
"size": 538371,
"is_downloadable": true,
"content_hash": "6542845d7b65ffc5358ebaa6981d991bab9fda194afa48bd727fcbe9e4a3158b"
}
创建文件夹
POST /dropbox/2/files/create_folder_v2
Content-Type: application/json
{
"path": "/New Folder",
"autorename": false
}
响应：
{
"metadata": {
"name": "New Folder",
"path_lower": "/new folder",
"path_display": "/New Folder",
"id": "id:Awe3Av8A8YYAAAAAAAAABw"
}
}
复制文件或文件夹
POST /dropbox/2/files/copy_v2
Content-Type: application/json
{
"from_path": "/source/file.pdf",
"to_path": "/destination/file.pdf",
"autorename": false
}
响应：
{
"metadata": {
".tag": "file",
"name": "file.pdf",
"path_lower": "/destination/file.pdf",
"path_display": "/destination/file.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAACA"
}
}
移动文件或文件夹
POST /dropbox/2/files/move_v2
Content-Type: application/json
{
"from_path": "/old/location/file.pdf",
"to_path": "/new/location/file.pdf",
"autorename": false
}
响应：
{
"metadata": {
".tag": "file",
"name": "file.pdf",
"path_lower": "/new/location/file.pdf",
"path_display": "/new/location/file.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAACA"
}
}
删除文件或文件夹
POST /dropbox/2/files/delete_v2
Content-Type: application/json
{
"path": "/file-to-delete.pdf"
}
响应：
{
"metadata": {
".tag": "file",
"name": "file-to-delete.pdf",
"path_lower": "/file-to-delete.pdf",
"path_display": "/file-to-delete.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAABQ"
}
}
获取临时下载链接
POST /dropbox/2/files/get_temporary_link
Content-Type: application/json
{
"path": "/document.pdf"
}
响应：
{
"metadata": {
"name": "document.pdf",
"path_lower": "/document.pdf",
"path_display": "/document.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAABQ",
"size": 538371,
"is_downloadable": true
},
"link": "https://uc785ee484c03b6556c091ea4491.dl.dropboxusercontent.com/cd/0/get/..."
}
该链接在4小时内有效。
搜索
搜索文件
POST /dropbox/2/files/search_v2
Content-Type: application/json
{
"query": "document",
"options": {
"path": "",
"max_results": 100,
"file_status": "active",
"filename_only": false
}
}
响应：
{
"has_more": false,
"matches": [
{
"highlight_spans": [],
"match_type": {
".tag": "filename"
},
"metadata": {
".tag": "metadata",
"metadata": {
".tag": "file",
"name": "document.pdf",
"path_display": "/document.pdf",
"path_lower": "/document.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAABw"
}
}
}
]
}
继续搜索
POST /dropbox/2/files/search/continue_v2
Content-Type: application/json
{
"cursor": "..."
}
文件版本
列出版本
POST /dropbox/2/files/list_revisions
Content-Type: application/json
{
"path": "/document.pdf",
"mode": "path",
"limit": 10
}
响应：
{
"is_deleted": false,
"entries": [
{
"name": "document.pdf",
"path_lower": "/document.pdf",
"path_display": "/document.pdf",
"id": "id:Awe3Av8A8YYAAAAAAAAABQ",
"client_modified": "2026-02-09T19:58:12Z",
"server_modified": "2026-02-09T19:58:13Z",
"rev": "016311c063b4f8700000002caa704e3",
"size": 538371,
"is_downloadable": true
}
],
"has_more": false
}
恢复文件
POST /dropbox/2/files/restore
Content-Type: application/json
{
"path": "/document.pdf",
"rev": "016311c063b4f8700000002caa704e3"
}
标签
获取标签
POST /dropbox/2/files/tags/get
Content-Type: application/json
{
"paths": ["/document.pdf", "/folder"]
}
响应：
{
"paths_to_tags": [
{
"path": "/document.pdf",
"tags": [
{
".tag": "user_generated_tag",
"tag_text": "important"
}
]
},
{
"path": "/folder",
"tags": []
}
]
}
添加标签
POST /dropbox/2/files/tags/add
Content-Type: application/json
{
"path": "/document.pdf",
"tag_text": "important"
}
返回null表示操作成功。
注意：标签文本必须符合模式[\w]+（仅限字母数字和下划线，不能使用连字符或空格）。
移除标签
POST /dropbox/2/files/tags/remove
Content-Type: application/json
{
"path": "/document.pdf",
"tag_text": "important"
}
返回null表示操作成功。
批量操作
批量删除
POST /dropbox/2/files/delete_batch
Content-Type: application/json
{
"entries": [
{"path": "/file1.pdf"},
{"path": "/file2.pdf"}
]
}
返回异步任务ID。可通过/files/delete_batch/check接口查询任务状态。
批量复制
POST /dropbox/2/files/copy_batch_v2
Content-Type: application/json
{
"entries": [
{"from_path": "/source/file1.pdf", "to_path": "/dest/file1.pdf"},
{"from_path": "/source/file2.pdf", "to_path": "/dest/file2.pdf"}
],
"autorename": false
}
批量移动
POST /dropbox/2/files/move_batch_v2
Content-Type: application/json
{
"entries": [
{"from_path": "/old/file1.pdf", "to_path": "/new/file1.pdf"},
{"from_path": "/old/file2.pdf", "to_path": "/new/file2.pdf"}
],
"autorename": false
}
分页机制
Dropbox采用基于游标的分页方式。当has_more字段为true时，需使用返回的游标调用/continue端点继续获取数据。
import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
'Content-Type': 'application/json'
}
# Initial request
response = requests.post(
'https://gateway.maton.ai/dropbox/2/files/list_folder',
headers=headers,
json={'path': '', 'limit': 100}
)
result = response.json()
all_entries = result['entries']
# Continue while has_more is True
while result.get('has_more'):
response = requests.post(
'https://gateway.maton.ai/dropbox/2/files/list_folder/continue',
headers=headers,
json={'cursor': result['cursor']}
)
result = response.json()
all_entries.extend(result['entries'])
print(f"Total entries: {len(all_entries)}")
代码示例
JavaScript
const response = await fetch(
'https://gateway.maton.ai/dropbox/2/files/list_folder',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ path: '' })
}
);
const data = await response.json();
console.log(data.entries);
Python
import os
import requests
response = requests.post(
'https://gateway.maton.ai/dropbox/2/files/list_folder',
headers={
'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
'Content-Type': 'application/json'
},
json={'path': ''}
)
data = response.json()
print(data['entries'])
Python（创建文件夹与搜索）
import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
'Content-Type': 'application/json'
}
# Create folder
response = requests.post(
'https://gateway.maton.ai/dropbox/2/files/create_folder_v2',
headers=headers,
json={'path': '/My New Folder', 'autorename': False}
)
folder = response.json()
print(f"Created folder: {folder['metadata']['path_display']}")
# Search for files
response = requests.post(
'https://gateway.maton.ai/dropbox/2/files/search_v2',
headers=headers,
json={'query': 'document'}
)
results = response.json()
print(f"Found {len(results['matches'])} matches")
注意事项
- 所有Dropbox API v2端点均采用HTTP POST方法
- 请求体为JSON格式（非表单编码）
- 使用空字符串
""作为根文件夹路径 - 路径不区分大小写但保留大小写
- 文件ID（例如：
id:Awe3Av8A8YYAAAAAAAAABQ）在文件移动或重命名后仍保持不变 - 标签文本必须匹配模式
[\w]+（仅限字母数字和下划线） - 临时下载链接在4小时后过期
- 速率限制较为宽松且按用户计
- 重要提示：通过管道将curl输出传递给
jq或其他命令时，在某些shell环境中，环境变量如$MATON_API_KEY可能无法正确展开
错误处理
| 状态码 | 含义 |
|---|---|
| 400 | 缺少Dropbox连接或请求错误 |
| 401 | Maton API密钥无效或缺失 |
| 404 | 资源未找到 |
| 409 | 冲突（路径不存在、已存在等） |
| 429 | 请求频率受限 |
| 4xx/5xx | 来自Dropbox API的透传错误 |
错误响应包含详细信息：
{
"error_summary": "path/not_found/...",
"error": {
".tag": "path",
"path": {
".tag": "not_found"
}
}
}
故障排除：无效的API密钥
当收到“无效API密钥”错误时，在确认存在问题前，请务必遵循以下步骤：
- 检查
MATON_API_KEY环境变量是否已设置：
echo $MATON_API_KEY
- 通过列出连接来验证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
资源
微信扫一扫，打赏作者吧～文章底部电脑广告
手机广告位-内容正文底部
