OneDrive

通过 Microsoft Graph 实现受管理的 OAuth 认证，访问 OneDrive API。支持对文件、文件夹、驱动器及共享功能的完整增删改查操作。

快速开始

CLI：

maton one-drive item list

maton api '/one-drive/v1.0/me/drive/root/children'

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/one-drive/v1.0/me/drive/root/children')
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://api.maton.ai/one-drive/v1.0/{resource}

Maton 将请求代理至 graph.microsoft.com，并自动注入您的 OAuth 访问令牌。

安装

NPM：

npm install -g @maton/cli

Homebrew：

brew install maton-ai/cli/maton

认证

CLI：

maton login                          # 打开浏览器获取 API 密钥
maton login --interactive            # 跳过浏览器，手动粘贴 API 密钥
maton whoami                         # 查看当前认证状态

手动方式：

1. 访问 [maton.ai](https://maton.ai) 注册或登录账户
2. 进入 [maton.ai/settings](https://maton.ai/settings)
3. 复制您的 API 密钥
4. 将 API 密钥设置为环境变量 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

连接管理

在 https://api.maton.ai 管理您的 OneDrive OAuth 连接。

列出连接

CLI：

maton connection list one-drive --status ACTIVE

maton api -X GET /connections -f app=one-drive -f status=ACTIVE

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=one-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

创建连接

CLI：

maton connection create one-drive

maton api /connections -f app=one-drive

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'one-drive'}).encode()
req = urllib.request.Request('https://api.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

获取连接信息

CLI：

maton connection view {connection_id}

maton api /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T08:23:30.317909Z",
    "last_updated_time": "2026-02-07T08:24:04.925298Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "one-drive",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 完成 OAuth 授权流程。

删除连接

CLI：

maton connection delete {connection_id}

maton api -X DELETE /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

指定连接

若您拥有多个 OneDrive 连接，需明确指定使用哪一个：

CLI：

maton one-drive item list --connection {connection_id}

maton api /one-drive/v1.0/me/drive/root/children --connection {connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/one-drive/v1.0/me/drive')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

若存在多个连接，请始终指定具体连接以确保请求发送至正确的账户。

安全与权限

• 权限范围仅限于已连接 OneDrive 账户内的文件、文件夹及共享操作。
• 所有写入操作均需用户明确授权。 在执行创建、更新或删除操作前，请务必向用户确认目标资源及其预期影响。

API 参考

驱动器（Drives）

获取当前用户的驱动器

GET /one-drive/v1.0/me/drive

示例：

maton one-drive whoami

列出用户的所有驱动器

GET /one-drive/v1.0/me/drives

示例：

maton one-drive drive list

根据 ID 获取驱动器

GET /one-drive/v1.0/drives/{drive-id}

示例：

maton one-drive drive view {drive-id}

文件与文件夹

获取驱动器根目录

GET /one-drive/v1.0/me/drive/root

示例：

maton one-drive item view root

列出根目录下的子项

GET /one-drive/v1.0/me/drive/root/children

示例：

maton one-drive item list

根据 ID 获取项目

GET /one-drive/v1.0/me/drive/items/{item-id}

示例：

maton one-drive item view {item-id}

根据路径获取项目

使用冒号（:）语法通过路径访问项目：

GET /one-drive/v1.0/me/drive/root:/Documents/report.pdf

示例：

maton one-drive item view-by-path Documents/report.pdf

根据路径列出文件夹子项

GET /one-drive/v1.0/me/drive/root:/Documents:/children

示例：

maton one-drive item list Documents

获取项目的子项

GET /one-drive/v1.0/me/drive/items/{item-id}/children

示例：

maton one-drive item view {item-id} --expand children

特殊文件夹

通过名称访问已知特殊文件夹：

GET /one-drive/v1.0/me/drive/special/documents
GET /one-drive/v1.0/me/drive/special/photos
GET /one-drive/v1.0/me/drive/special/music
GET /one-drive/v1.0/me/drive/special/approot

示例：

maton one-drive item view --special documents

最近文件与共享文件

获取最近文件

GET /one-drive/v1.0/me/drive/recent

示例：

maton one-drive drive recent

获取与我共享的文件

GET /one-drive/v1.0/me/drive/sharedWithMe

示例：

maton one-drive drive shared

搜索

GET /one-drive/v1.0/me/drive/root/search(q='budget')

示例：

maton one-drive drive search 'budget'

创建文件夹

POST /one-drive/v1.0/me/drive/root:/Documents:/children
Content-Type: application/json

{
  "name": "Reports",
  "folder": {},
  "@microsoft.graph.conflictBehavior": "rename"
}

示例：

maton one-drive item create-folder Reports --path Documents

在指定父文件夹内创建文件夹：

POST /one-drive/v1.0/me/drive/items/{parent-id}/children
Content-Type: application/json

{
  "name": "Reports",
  "folder": {}
}

示例：

maton one-drive item create-folder Reports --parent-id {parent-id}

上传文件（简单上传 - 最大 4MB）

PUT /one-drive/v1.0/me/drive/root:/Documents/report.pdf:/content
Content-Type: application/pdf

{report.pdf 二进制内容}

示例：

maton one-drive item upload ./report.pdf --path Documents/report.pdf

上传大文件（可恢复上传）

对于超过 4MB 的文件，使用可恢复上传机制：

步骤 1：创建上传会话

POST /one-drive/v1.0/me/drive/root:/large-report.pdf:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  }
}

示例：

maton one-drive item upload ./large-report.pdf --path large-report.pdf --conflict rename

大于 4 MiB 的文件将自动启用可恢复上传会话。

响应示例：

{
  "uploadUrl": "https://sn3302.up.1drv.com/up/...",
  "expirationDateTime": "2024-02-08T10:00:00Z"
}

**步骤 2：向 uploadUrl 上传数据块**

下载文件

获取文件元数据以获取下载链接：

GET /one-drive/v1.0/me/drive/items/{item-id}

示例：

maton one-drive item view {item-id}

响应中包含 @microsoft.graph.downloadUrl —— 一个预认证的临时链接：

{
  "id": "...",
  "name": "document.pdf",
  "@microsoft.graph.downloadUrl": "https://public-sn3302.files.1drv.com/..."
}

可直接使用该链接下载文件内容（无需携带认证头）。

更新项目（重命名/移动）

PATCH /one-drive/v1.0/me/drive/items/{item-id}
Content-Type: application/json

{
  "name": "new-name.txt"
}

示例：

maton one-drive item update {item-id} --name new-name.txt

移动到其他文件夹：

PATCH /one-drive/v1.0/me/drive/items/{item-id}
Content-Type: application/json

{
  "parentReference": {
    "id": "{new-parent-id}"
  }
}

示例：

maton one-drive item move {item-id} --dest-id {new-parent-id}

复制项目

POST /one-drive/v1.0/me/drive/items/{item-id}/copy
Content-Type: application/json

{
  "parentReference": {
    "id": "{destination-folder-id}"
  },
  "name": "copied-file.txt"
}

示例：

maton one-drive item copy {item-id} --dest-id {destination-folder-id} --name copied-file.txt

返回 202 Accepted，并附带 Location 头用于监控复制进度。

删除项目

DELETE /one-drive/v1.0/me/drive/items/{item-id}

示例：

maton one-drive item delete {item-id}

成功后返回 204 No Content。

共享功能

创建共享链接

POST /one-drive/v1.0/me/drive/items/01ABCDEF/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous"
}

链接类型：

• view：只读访问
• edit：读写访问
• embed：可嵌入链接

作用范围：

• anonymous：任何持有链接的人
• organization：您所在组织内的任何人

示例：

maton one-drive item share 01ABCDEF --type view --scope anonymous

邀请特定用户（按人共享）

POST /one-drive/v1.0/me/drive/items/{item-id}/invite
Content-Type: application/json

{
  "recipients": [
    {"email": "user@example.com"}
  ],
  "roles": ["read"],
  "sendInvitation": true,
  "message": "Check out this file!"
}

示例：

maton one-drive item invite {item-id} --emails user@example.com --roles read --message 'Check out this file!'

查询参数

通过 OData 查询参数自定义响应：

• $select：选择特定字段：?$select=id,name,size
• $expand：包含关联资源：?$expand=children
• $filter：过滤结果：?$filter=file ne null（仅文件）
• $orderby：排序结果：?$orderby=name asc
• $top：限制返回数量：?$top=10

示例：

GET /one-drive/v1.0/me/drive/root/children?$select=id,name,size&$top=20&$orderby=name%20asc

maton one-drive item list --select id,name,size --top 20 --orderby 'name asc'

分页

OneDrive 使用基于游标的分页机制。CLI 会自动处理分页，使用 --paginate 参数。

示例：

maton one-drive item list --paginate

代码示例

CLI

# 搜索文件
maton one-drive drive search 'budget'

# 共享文件
maton one-drive item share 01ABCDEF --type view --scope anonymous

# 使用 --jq 提取特定字段（需配合 --json）
maton one-drive item view root --json --jq '.name'

JavaScript

// 列出根目录文件
const response = await fetch(
  'https://api.maton.ai/one-drive/v1.0/me/drive/root/children',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

// 上传文件
const uploadResponse = await fetch(
  'https://api.maton.ai/one-drive/v1.0/me/drive/root:/myfile.txt:/content',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'text/plain'
    },
    body: 'Hello, OneDrive!'
  }
);

Python

import os
import requests

# 列出根目录文件
response = requests.get(
    'https://api.maton.ai/one-drive/v1.0/me/drive/root/children',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
files = response.json()

# 上传文件
upload_response = requests.put(
    'https://api.maton.ai/one-drive/v1.0/me/drive/root:/myfile.txt:/content',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'text/plain'
    },
    data='Hello, OneDrive!'
)

注意事项

• OneDrive 使用 Microsoft Graph API（graph.microsoft.com）
• 项目 ID 在单个驱动器内唯一
• 使用冒号（:）语法进行路径定位：/root:/path/to/file
• ≤4MB 的文件可通过单次 PUT 上传；大于 4MB 的文件将自动使用可恢复上传会话
• @microsoft.graph.downloadUrl 返回的下载链接为预认证且有效期短暂
• 冲突处理选项：fail、replace、rename
• 在个人 OneDrive 账户中，只有 whoami 返回的用户自身驱动器 ID 可直接访问。drive list 中出现的 b!... 前缀 ID 在直接调用时会返回 HTTP 400 错误。应使用 me/drive 替代。
• 重要提示：使用 curl 命令时，若 URL 包含括号，请使用 curl -g 以禁用通配符解析
• 重要提示：当将 curl 输出管道给 jq 或其他命令时，某些 shell 环境中环境变量如 $MATON_API_KEY 可能无法正确展开

错误处理

错误响应格式

{
  "error": {
    "code": "itemNotFound",
    "message": "The resource could not be found."
  }
}

故障排查：API 密钥问题

CLI：

1. 检查认证状态：

maton whoami

1. 通过列出连接验证密钥有效性：

maton connection list

手动方式：

1. 确认 MATON_API_KEY 环境变量已设置：

echo $MATON_API_KEY

1. 通过列出连接验证密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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 路径以 one-drive 开头。例如：

• 正确：https://api.maton.ai/one-drive/v1.0/me/drive/root/children
• 错误：https://api.maton.ai/v1.0/me/drive/root/children

资源

• [OneDrive 开发者文档](https://learn.microsoft.com/en-us/onedrive/developer/)
• [Microsoft Graph API 参考](https://learn.microsoft.com/en-us/graph/)