Box技能使用说明

2026-03-28 新闻来源：网淘吧围观:16

电脑广告

手机广告

Box

使用托管的OAuth认证访问Box API。管理文件、文件夹、协作、共享链接和云存储。

快速开始

# 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

基础URL

https://gateway.maton.ai/box/2.0/{resource}

网关将请求代理至api.box.com/2.0并自动注入您的OAuth令牌。

认证

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

Authorization: Bearer $MATON_API_KEY

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

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

登录或前往maton.ai
创建账户前往
maton.ai/settings

复制您的API密钥

连接管理在https://ctrl.maton.ai

列出连接

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

创建连接

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

获取连接

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": "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授权。

删除连接

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

指定连接

如果您有多个Box连接，请使用Maton-Connection标头指定要使用的连接：

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参考

用户信息

获取当前用户

GET /box/2.0/users/me

响应：

{
  "type": "user",
  "id": "48806418054",
  "name": "Chris",
  "login": "chris@example.com",
  "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 /box/2.0/users/{user_id}

文件夹操作

获取根文件夹

根文件夹的ID为0：

GET /box/2.0/folders/0

获取文件夹

GET /box/2.0/folders/{folder_id}

响应：

{
  "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"
}

列出文件夹内容

GET /box/2.0/folders/{folder_id}/items

查询参数：

limit- 返回的最大项目数（默认 100，最大 1000）
offset- 用于分页的偏移量
fields- 要包含的字段的逗号分隔列表

响应：

{
  "total_count": 1,
  "entries": [
    {
      "type": "folder",
      "id": "365036703666",
      "name": "Subfolder"
    }
  ],
  "offset": 0,
  "limit": 100
}

创建文件夹

POST /box/2.0/folders
Content-Type: application/json

{
  "name": "New Folder",
  "parent": {"id": "0"}
}

响应：

{
  "type": "folder",
  "id": "365037181307",
  "name": "New Folder",
  "created_at": "2026-02-08T14:56:17-08:00"
}

更新文件夹

PUT /box/2.0/folders/{folder_id}
Content-Type: application/json

{
  "name": "Updated Folder Name",
  "description": "Updated description"
}

复制文件夹

POST /box/2.0/folders/{folder_id}/copy
Content-Type: application/json

{
  "name": "Copied Folder",
  "parent": {"id": "0"}
}

删除文件夹

DELETE /box/2.0/folders/{folder_id}

查询参数：

recursive- 设置为true以删除非空文件夹

成功时返回 204 无内容。

文件操作

获取文件信息

GET /box/2.0/files/{file_id}

下载文件

GET /box/2.0/files/{file_id}/content

返回下载URL的重定向。

上传文件

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>

注意：文件上传使用不同的基础URL：upload.box.com

更新文件信息

PUT /box/2.0/files/{file_id}
Content-Type: application/json

{
  "name": "renamed-file.txt",
  "description": "File description"
}

复制文件

POST /box/2.0/files/{file_id}/copy
Content-Type: application/json

{
  "name": "copied-file.txt",
  "parent": {"id": "0"}
}

删除文件

DELETE /box/2.0/files/{file_id}

成功时返回204 No Content。

获取文件版本

GET /box/2.0/files/{file_id}/versions

共享链接

通过更新文件或文件夹创建共享链接：

PUT /box/2.0/folders/{folder_id}
Content-Type: application/json

{
  "shared_link": {
    "access": "open"
  }
}

访问级别：

公开- 任何拥有链接的人
企业- 仅限企业内用户
协作者- 仅限协作者

响应包括：

{
  "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
    }
  }
}

协作

列出文件夹协作

GET /box/2.0/folders/{folder_id}/collaborations

创建协作

POST /box/2.0/collaborations
Content-Type: application/json

{
  "item": {"type": "folder", "id": "365037181307"},
  "accessible_by": {"type": "user", "login": "user@example.com"},
  "role": "editor"
}

角色：编辑,查看者,预览者,上传者,预览上传者,查看上传者,共同所有者

更新协作

PUT /box/2.0/collaborations/{collaboration_id}
Content-Type: application/json

{
  "role": "viewer"
}

删除协作

DELETE /box/2.0/collaborations/{collaboration_id}

搜索

GET /box/2.0/search?query=document

查询参数：

查询- 搜索查询（必需）
类型- 按类型筛选：文件,文件夹,网络链接
文件扩展名- 逗号分隔的扩展名
ancestor_folder_ids- 限制为特定文件夹
limit- 最大结果数（默认 30）
offset- 分页偏移量

响应：

{
  "total_count": 5,
  "entries": [...],
  "limit": 30,
  "offset": 0,
  "type": "search_results_items"
}

事件

GET /box/2.0/events

查询参数：

stream_type-all,changes,sync,admin_logs
stream_position- 起始位置
limit- 要返回的最大事件数

响应：

{
  "chunk_size": 4,
  "next_stream_position": "30401068076164269",
  "entries": [...]
}

回收站

列出已删除的项目

GET /box/2.0/folders/trash/items

获取回收站项目

GET /box/2.0/files/{file_id}/trash
GET /box/2.0/folders/{folder_id}/trash

恢复回收站项目

POST /box/2.0/files/{file_id}
POST /box/2.0/folders/{folder_id}

永久删除

DELETE /box/2.0/files/{file_id}/trash
DELETE /box/2.0/folders/{folder_id}/trash

收藏集（收藏夹）

列出收藏集

GET /box/2.0/collections

响应：

{
  "total_count": 1,
  "entries": [
    {
      "type": "collection",
      "name": "Favorites",
      "collection_type": "favorites",
      "id": "35223030868"
    }
  ]
}

获取收藏集项目

GET /box/2.0/collections/{collection_id}/items

Webhook

列出 Webhook

GET /box/2.0/webhooks

创建 Webhook

POST /box/2.0/webhooks
Content-Type: application/json

{
  "target": {"id": "365037181307", "type": "folder"},
  "address": "https://example.com/webhook",
  "triggers": ["FILE.UPLOADED", "FILE.DOWNLOADED"]
}

注意：创建 Webhook 可能需要企业权限。

删除 Webhook

DELETE /box/2.0/webhooks/{webhook_id}

分页

Box 使用基于偏移量的分页：

GET /box/2.0/folders/0/items?limit=100&offset=0
GET /box/2.0/folders/0/items?limit=100&offset=100

部分端点使用基于标记的分页，通过标记参数。

响应：

{
  "total_count": 250,
  "entries": [...],
  "offset": 0,
  "limit": 100
}

代码示例

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

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（创建文件夹）

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']}")

备注

根文件夹ID为0
文件上传使用upload.box.com而非api.box.com
删除操作成功时返回204 No Content
使用fields参数可请求特定字段并减小响应大小
共享链接可设置密码保护和过期日期
部分操作（列出用户、创建网络钩子）需要企业管理员权限
ETag可通过If-Match请求头实现条件更新
重要提示：当通过管道将curl输出传递给jq或其他命令时，某些shell环境中$MATON_API_KEY等环境变量可能无法正确展开

错误处理

状态码	含义
400	缺少 Box 连接或请求错误
401	无效或缺少 Maton API 密钥
403	操作权限不足
404	资源未找到
409	冲突（例如，存在同名项目）
429	请求频率受限
4xx/5xx	来自 Box API 的直通错误

Box 错误包含详细消息：

{
  "type": "error",
  "status": 409,
  "code": "item_name_in_use",
  "message": "Item with the same name already exists"
}

故障排除：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

故障排除：无效应用名称

确保您的 URL 路径以box。例如：

正确：https://gateway.maton.ai/box/2.0/users/me
错误：https://gateway.maton.ai/2.0/users/me

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Prompt Injection Guard技能使用说明下一篇：multi-factor-strategy技能使用说明

Box技能使用说明

Box

快速开始

基础URL

认证

获取您的API密钥

复制您的API密钥

列出连接

创建连接

获取连接

删除连接

指定连接

API参考

用户信息

获取当前用户

获取用户

文件夹操作

获取根文件夹

获取文件夹

列出文件夹内容

创建文件夹

更新文件夹

复制文件夹

删除文件夹

文件操作

获取文件信息

下载文件

上传文件

更新文件信息

复制文件

删除文件

获取文件版本

共享链接

协作

列出文件夹协作

创建协作

更新协作

删除协作

搜索

事件

回收站

列出已删除的项目

获取回收站项目

恢复回收站项目

永久删除

收藏集（收藏夹）

列出收藏集

获取收藏集项目

最近项目

Webhook

列出 Webhook

创建 Webhook

删除 Webhook

分页

代码示例

JavaScript

Python

Python（创建文件夹）

备注

错误处理

故障排除：API 密钥问题

故障排除：无效应用名称

资源

相关文章

推荐文章

热门浏览

标签列表