OneDrive

通过 Microsoft Graph 的托管 OAuth 认证访问 OneDrive API。支持对文件、文件夹、驱动器和共享内容的完整 CRUD 操作。

快速开始

CLI：

maton one-drive item list

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

Python：

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))

基础 URL

https://api.maton.ai/one-drive/v1.0/{resource}

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

安装

NPM：

npm install -g @maton-ai/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：

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))

创建连接

CLI：

maton connection create one-drive

maton api /connections -f app=one-drive

Python：

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))

查看连接

CLI：

maton connection view {connection_id}

maton api /connections/{connection_id}

Python：

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))

响应示例：

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

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))

指定连接

如果您拥有多个 OneDrive 连接，请明确指定使用哪一个：

CLI：

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

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

Python：

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))

当存在多个连接时，始终指定连接 ID 以确保请求发送到正确的账户。

安全与权限

• 权限范围仅限于已连接 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

示例：

yaml

name: Microsoft OneDrive

version: 1.0.5

description: 与 Microsoft OneDrive 交互，支持文件列表、上传、下载、共享等操作。

summary: 通过 CLI 工具管理 OneDrive 文件和文件夹，支持多种操作如创建、上传、下载、分享等。

tags:

- cloud

- storage

- file

- microsoft

- one-drive

author: skillppc

license: MIT

Microsoft OneDrive

基本操作

列出项目

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

在指定父文件夹内创建文件夹，使用父文件夹 ID：

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 binary content}

示例：

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

上传文件（大文件上传 - 支持断点续传）

对于超过 4MB 的文件，使用断点续传上传。

步骤一：创建上传会话

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

**步骤二：将数据块上传到 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 示例

// 示例：使用 Node.js 调用 OneDrive API
const axios = require('axios');

const headers = {
  Authorization: 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};

// 获取文件列表
axios.get('https://graph.microsoft.com/v1.0/me/drive/root/children', { headers })
  .then(response => console.log(response.data.value))
  .catch(error => console.error(error.response.data));

markdown
# Skill: Microsoft OneDrive
Version: 1.0.5
Chunk: 3/3

## 示例代码

### 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 账户中，仅用户自身的驱动器 ID（通过 `whoami` 返回）可直接访问。`drive list` 中出现的以 `b!...` 开头的额外 ID 在通过此方式获取时会返回 HTTP 400 错误。应使用 `me/drive` 代替
- 重要提示：使用 curl 命令时，若 URL 包含方括号，请使用 `curl -g` 以禁用通配符解析
- 重要提示：将 curl 输出管道传递给 `jq` 等命令时，某些 shell 环境中环境变量如 `$MATON_API_KEY` 可能无法正确展开

## 错误处理

| 状态码 | 含义 |
|--------|------|
| 400 | 缺少 OneDrive 连接或请求无效 |
| 401 | Maton API 密钥无效或缺失 |
| 403 | 权限不足 |
| 404 | 项目未找到 |
| 409 | 冲突（例如文件已存在） |
| 429 | 请求频率受限（请检查 `Retry-After` 头部） |
| 4xx/5xx | 透传自 Microsoft Graph API 的错误 |

### 错误响应格式

{

"error": {

"code": "itemNotFound",

"message": "该资源未找到。"

}

}

### 故障排查：API 密钥问题

**CLI 方式：**

1. 检查当前认证状态：

maton whoami

2. 验证 API 密钥是否有效，通过列出连接信息：

maton connection list

**手动方式：**

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

echo $MATON_API_KEY

2. 通过以下命令验证 API 密钥有效性，列出连接：

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/api/overview)
- [DriveItem 资源](https://learn.microsoft.com/en-us/graph/api/resources/driveitem)
- [Drive 资源](https://learn.microsoft.com/en-us/graph/api/resources/drive)
- [共享与权限](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/concepts/sharing)
- [大文件上传](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession)
- [Maton CLI 手册](https://cli.maton.ai/manual)
- [Maton 社区](https://discord.com/invite/dBfFAcefs2)
- [Maton 支持邮箱](mailto:support@maton.ai)