Dropbox

在 Dropbox 中上传、下载、列出和搜索文件。支持自动刷新访问令牌（access token）。

必需的凭据

请将上述变量保存至 ~/.config/atlas/dropbox.env：

DROPBOX_APP_KEY=your_app_key
DROPBOX_APP_SECRET=your_app_secret
DROPBOX_REFRESH_TOKEN=xxx...
DROPBOX_ACCESS_TOKEN=sl.u.xxx...

初始配置（仅需一次）

1. 创建 Dropbox 应用

1. 访问 https://www.dropbox.com/developers/apps
2. 点击“Create app”（创建应用）
3. 选择“Scoped access”（作用域访问）
4. 选择“Full Dropbox”（完整 Dropbox 权限），或选择“App folder”（应用专属文件夹，权限受限）
5. 为您的应用命名
6. 记录下App key 和 App secret

2. 配置权限

在应用设置中的 “Permissions”（权限）页面，启用以下权限：

• files.metadata.read
• files.metadata.write
• files.content.read
• files.content.write
• account_info.read

点击 “Submit”（提交）以保存设置。

3. 执行 OAuth 流程

生成授权 URL：

import urllib.parse

APP_KEY = "your_app_key"

params = {
    "client_id": APP_KEY,
    "response_type": "code",
    "token_access_type": "offline"  # 此参数将返回 refresh token！
}

auth_url = "https://www.dropbox.com/oauth2/authorize?" + urllib.parse.urlencode(params)
print(auth_url)

将该 URL 提供给用户。用户需执行以下操作：

1. 在浏览器中打开该链接
2. 授权该应用访问其 Dropbox 账户
3. 获取一个授权码（authorization code）

4. 使用授权码换取令牌

curl -X POST "https://api.dropboxapi.com/oauth2/token" 
  -d "code=AUTHORIZATION_CODE" 
  -d "grant_type=authorization_code" 
  -d "client_id=APP_KEY" 
  -d "client_secret=APP_SECRET"

响应中包含：

• access_token — 短期有效（约 4 小时）
• refresh_token — 长期有效（除非被显式撤销，否则永不过期）

使用方法

# 查询账户信息
dropbox.py account

# 列出指定文件夹内容
dropbox.py ls "/path/to/folder"

# 搜索文件
dropbox.py search "query"

# 下载文件
dropbox.py download "/path/to/file.pdf"

# 上传文件
dropbox.py upload local_file.pdf "/Dropbox/path/remote_file.pdf"

令牌自动刷新

脚本会自动处理令牌刷新逻辑：

1. 当收到 401 Unauthorized 响应时，使用 refresh token 获取新的 access token
2. 将新获取的 access token 更新至 dropbox.env 文件中
3. 重试原始请求

令牌生命周期

*Refresh token 仅在被显式撤销或应用访问权限被移除时才会失效。

常见问题排查

刷新令牌时返回 401 Unauthorized：

• 应用可能已被断开连接 —— 请重新执行第 3 步的 OAuth 流程

返回 403 Forbidden：

• 请检查 Dropbox 开发者控制台中应用的权限配置

路径相关错误：

• Dropbox 路径以 / 开头，且不区分大小写
• 即使在 Windows 系统上也请始终使用正斜杠（/）

API 参考文档

• OAuth 指南：https://developers.dropbox.com/oauth-guide
• API 探索器（API Explorer）：https://dropbox.github.io/dropbox-api-v2-explorer/