介绍
# Box
通过托管的 OAuth 身份验证访问 Box API。管理文件、文件夹、协作、共享链接和云存储。
## Quick Start
```bash # Get current user info python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/box/2.0/users/me') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/box/2.0/{resource} ```
网关将请求代理到 `api.box.com/2.0` 并自动注入您的 OAuth 令牌。
## Authentication
所有请求都需要在 Authorization 头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**Environment Variable:** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## Connection Management
在 `https://ctrl.maton.ai` 管理您的 Box OAuth 连接。
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=box&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 ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'box'}).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 ```
### Get Connection
```bash 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 ```
**Response:** ```json { "connection": { "connection_id": "bd484938-0902-4fc0-9ffb-2549d7d91f1d", "status": "ACTIVE", "creation_time": "2026-02-08T21:14:41.808115Z", "last_updated_time": "2026-02-08T21:16:10.100340Z", "url": "https://connect.maton.ai/?session_token=...", "app": "box", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### Delete Connection
```bash 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 ```
### Specifying Connection
如果您有多个 Box 连接，请使用 `Maton-Connection` 头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/box/2.0/users/me') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'bd484938-0902-4fc0-9ffb-2549d7d91f1d') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API Reference
### User Info
#### Get Current User
```bash GET /box/2.0/users/me ```
**Response:** ```json { "type": "user", "id": "48806418054", "name": "Chris", "login": "[email protected]", "created_at": "2026-02-08T13:12:34-08:00", "modified_at": "2026-02-08T13:12:35-08:00", "language": "en", "timezone": "America/Los_Angeles", "space_amount": 10737418240, "space_used": 0, "max_upload_size": 262144000, "status": "active", "avatar_url": "https://app.box.com/api/avatar/large/48806418054" } ```
#### Get User
```bash GET /box/2.0/users/{user_id} ```
### Folder Operations
#### Get Root Folder
根文件夹的 ID 为 `0`：
```bash GET /box/2.0/folders/0 ```
#### Get Folder
```bash GET /box/2.0/folders/{folder_id} ```
**Response:** ```json { "type": "folder", "id": "365037181307", "name": "My Folder", "description": "Folder description", "size": 0, "path_collection": { "total_count": 1, "entries": [ {"type": "folder", "id": "0", "name": "All Files"} ] }, "created_by": {"type": "user", "id": "48806418054", "name": "Chris"}, "owned_by": {"type": "user", "id": "48806418054", "name": "Chris"}, "item_status": "active" } ```
#### List Folder Items
```bash GET /box/2.0/folders/{folder_id}/items ```
Query parameters: - `limit` - 要返回的最大项目数（默认 100，最大 1000） - `offset` - 分页偏移量 - `fields` - 要包含的字段的逗号分隔列表
**Response:** ```json { "total_count": 1, "entries": [ { "type": "folder", "id": "365036703666", "name": "Subfolder" } ], "offset": 0, "limit": 100 } ```
#### Create Folder
```bash POST /box/2.0/folders Content-Type: application/json
{ "name": "New Folder", "parent": {"id": "0"} } ```
**Response:** ```json { "type": "folder", "id": "365037181307", "name": "New Folder", "created_at": "2026-02-08T14:56:17-08:00" } ```
#### Update Folder
```bash PUT /box/2.0/folders/{folder_id} Content-Type: application/json
{ "name": "Updated Folder Name", "description": "Updated description" } ```
#### Copy Folder
```bash POST /box/2.0/folders/{folder_id}/copy Content-Type: application/json
{ "name": "Copied Folder", "parent": {"id": "0"} } ```
#### Delete Folder
```bash DELETE /box/2.0/folders/{folder_id} ```
Query parameters: - `recursive` - 设置为 `true` 以删除非空文件夹
成功时返回 204 No Content。
### File Operations
#### Get File Info
```bash GET /box/2.0/files/{file_id} ```
#### Download File
```bash GET /box/2.0/files/{file_id}/content ```
返回重定向到下载 URL。
#### Upload File
```bash POST https://upload.box.com/api/2.0/files/content Content-Type: multipart/form-data
attributes={"name":"file.txt","parent":{"id":"0"}} file=<binary data> ```
**Note:** 文件上传使用不同的基础 URL：`upload.box.com`
#### Update File Info
```bash PUT /box/2.0/files/{file_id} Content-Type: application/json
{ "name": "renamed-file.txt", "description": "File description" } ```
#### Copy File
```bash POST /box/2.0/files/{file_id}/copy Content-Type: application/json
{ "name": "copied-file.txt", "parent": {"id": "0"} } ```
#### Delete File
```bash DELETE /box/2.0/files/{file_id} ```
成功时返回 204 No Content。
#### Get File Versions
```bash GET /box/2.0/files/{file_id}/versions ```
### Shared Links
通过更新文件或文件夹创建共享链接：
```bash PUT /box/2.0/folders/{folder_id} Content-Type: application/json
{ "shared_link": { "access": "open" } } ```
Access levels: - `open` - 任何拥有链接的人 - `company` - 仅企业内的用户 - `collaborators` - 仅协作者
**Response includes:** ```json { "shared_link": { "url": "https://app.box.com/s/sisarrztrenabyygfwqggbwommf8uucv", "access": "open", "effective_access": "open", "is_password_enabled": false, "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } ```
### Collaborations
#### List Folder Collaborations
```bash GET /box/2.0/folders/{folder_id}/collaborations ```
#### Create Collaboration
```bash POST /box/2.0/collaborations Content-Type: application/json
{ "item": {"type": "folder", "id": "365037181307"}, "accessible_by": {"type": "user", "login": "[email protected]"}, "role": "editor" } ```
Roles: `editor`, `viewer`, `previewer`, `uploader`, `previewer_uploader`, `viewer_uploader`, `co-owner`
#### Update Collaboration
```bash PUT /box/2.0/collaborations/{collaboration_id} Content-Type: application/json
{ "role": "viewer" } ```
#### Delete Collaboration
```bash DELETE /box/2.0/collaborations/{collaboration_id} ```
### Search
```bash GET /box/2.0/search?query=document ```
Query parameters: - `query` - 搜索查询（必填） - `type` - 按类型筛选：`file`, `folder`, `web_link` - `file_extensions` - 逗号分隔的扩展名 - `ancestor_folder_ids` - 限制为特定文件夹 - `limit` - 最大结果数（默认 30） - `offset` - 分页偏移量
**Response:** ```json { "total_count": 5, "entries": [...], "limit": 30, "offset": 0, "type": "search_results_items" } ```
### Events
```bash GET /box/2.0/events ```
Query parameters: - `stream_type` - `all`, `changes`, `sync`, `admin_logs` - `stream_position` - 开始位置 - `limit` - 要返回的最大事件数
**Response:** ```json { "chunk_size": 4, "next_stream_position": "30401068076164269", "entries": [...] } ```
### Trash
#### List Trashed Items
```bash GET /box/2.0/folders/trash/items ```
#### Get Trashed Item
```bash GET /box/2.0/files/{file_id}/trash GET /box/2.0/folders/{folder_id}/trash ```
#### Restore Trashed Item
```bash POST /box/2.0/files/{file_id} POST /box/2.0/folders/{folder_id} ```
#### Permanently Delete
```bash DELETE /box/2.0/files/{file_id}/trash DELETE /box/2.0/folders/{folder_id}/trash ```
### Collections (Favorites)
#### List Collections
```bash GET /box/2.0/collections ```
**Response:** ```json { "total_count": 1, "entries": [ { "type": "collection", "name": "Favorites", "collection_type": "favorites", "id": "35223030868" } ] } ```
#### Get Collection Items
```bash GET /box/2.0/collections/{collection_id}/items ```
### Recent Items
```bash GET /box/2.0/recent_items ```
### Webhooks
#### List Webhooks
```bash GET /box/2.0/webhooks ```
#### Create Webhook
```bash POST /box/2.0/webhooks Content-Type: application/json
{ "target": {"id": "365037181307", "type": "folder"}, "address": "https://example.com/webhook", "triggers": ["FILE.UPLOADED", "FILE.DOWNLOADED"] } ```
**Note:** 创建 Webhook 可能需要企业权限。
#### Delete Webhook
```bash DELETE /box/2.0/webhooks/{webhook_id} ```
## Pagination
Box 使用基于偏移量的分页：
```bash GET /box/2.0/folders/0/items?limit=100&offset=0 GET /box/2.0/folders/0/items?limit=100&offset=100 ```
某些端点使用基于标记的分页，并带有 `marker` 参数。
**Response:** ```json { "total_count": 250, "entries": [...], "offset": 0, "limit": 100 } ```
## Code Examples
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/box/2.0/folders/0/items', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/box/2.0/folders/0/items', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
### Python (Create Folder)
```python import os import requests
response = requests.post( 'https://gateway.maton.ai/box/2.0/folders', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'name': 'New Folder', 'parent': {'id': '0'} } ) folder = response.json() print(f"Created folder: {folder['id']}") ```
## Notes
- 根文件夹 ID 为 `0` - 文件上传使用 `upload.box.com` 而不是 `api.box.com` - 删除操作成功时返回 204 No Content - 使用 `fields` 参数请求特定字段以减少响应大小 - 共享链接可以设置密码保护和过期日期 - 某些操作（列出用户、创建 webhooks）需要企业管理员权限 - ETags 可以通过 `If-Match` 头用于条件更新 - 重要提示：当将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## Error Handling
| Status | Meaning | |--------|---------| | 400 | 缺少 Box 连接或错误请求 | | 401 | Maton API 密钥无效或缺失 | | 403 | 操作权限不足 | | 404 | 资源未找到 | | 409 | 冲突（例如，存在同名项目） | | 429 | 速率受限 | | 4xx/5xx | 来自 Box API 的透传错误 |
Box 错误包含详细信息： ```json { "type": "error", "status": 409, "code": "item_name_in_use", "message": "Item with the same name already exists" } ```
### Troubleshooting: API Key Issues
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接验证 API 密钥是否有效：
```bash 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 ```
### Troubleshooting: Invalid App Name
1. 确保您的 URL 路径以 `box` 开头。例如：
- 正确：`https://gateway.maton.ai/box/2.0/users/me` - 错误：`https://gateway.maton.ai/2.0/users/me`
## Resources
- [Box API Reference](https://developer.box.com/reference) - [Box Developer Documentation](https://developer.box.com/guides) - [Authentication Guide](https://developer.box.com/guides/authentication) - [Box SDKs](https://developer.box.com/sdks-and-tools) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])