介绍
# OneDrive
通过 Microsoft Graph 使用托管 OAuth 身份验证访问 OneDrive API。通过完整的 CRUD 操作管理文件、文件夹、驱动器和共享。
## Quick Start
```bash # List files in OneDrive root python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.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 ```
## Base URL
``` https://gateway.maton.ai/one-drive/v1.0/{resource} ```
网关将请求代理到 `graph.microsoft.com` 并自动注入您的 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` 管理您的 OneDrive OAuth 连接。
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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 ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'one-drive'}).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": "3f17fb58-4515-4840-8ef6-2bbf0fa67e2c", "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 授权。
### 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
如果您有多个 OneDrive 连接，请使用 `Maton-Connection` 请求头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/one-drive/v1.0/me/drive') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '3f17fb58-4515-4840-8ef6-2bbf0fa67e2c') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早）的活动连接。
## API Reference
### Drives
#### Get Current User's Drive
```bash GET /one-drive/v1.0/me/drive ```
**Response:** ```json { "id": "b!F3Y7M0VT80OO9iu_D6Z-LA...", "driveType": "personal", "name": "OneDrive", "owner": { "user": { "displayName": "John Doe", "id": "d4648f06c91d9d3d" } }, "quota": { "total": 5368709120, "used": 1234567, "remaining": 5367474553 } } ```
#### List User's Drives
```bash GET /one-drive/v1.0/me/drives ```
#### Get Drive by ID
```bash GET /one-drive/v1.0/drives/{drive-id} ```
### Files and Folders
#### Get Drive Root
```bash GET /one-drive/v1.0/me/drive/root ```
#### List Root Children
```bash GET /one-drive/v1.0/me/drive/root/children ```
**Response:** ```json { "value": [ { "id": "F33B7653325337C3!s88...", "name": "Documents", "folder": { "childCount": 5 }, "createdDateTime": "2024-01-15T10:30:00Z", "lastModifiedDateTime": "2024-02-01T14:20:00Z" }, { "id": "F33B7653325337C3!s3f...", "name": "report.pdf", "file": { "mimeType": "application/pdf", "hashes": { "sha1Hash": "cf23df2207d99a74fbe169e3eba035e633b65d94" } }, "size": 35212 } ] } ```
#### Get Item by ID
```bash GET /one-drive/v1.0/me/drive/items/{item-id} ```
#### Get Item by Path
使用冒号（`:`）语法通过路径访问项目：
```bash GET /one-drive/v1.0/me/drive/root:/Documents/report.pdf ```
#### List Folder Children by Path
```bash GET /one-drive/v1.0/me/drive/root:/Documents:/children ```
#### Get Item Children
```bash GET /one-drive/v1.0/me/drive/items/{item-id}/children ```
### Special Folders
按名称访问已知文件夹：
```bash 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 ```
### Recent and Shared
#### Get Recent Files
```bash GET /one-drive/v1.0/me/drive/recent ```
#### Get Files Shared With Me
```bash GET /one-drive/v1.0/me/drive/sharedWithMe ```
### Search
```bash GET /one-drive/v1.0/me/drive/root/search(q='{query}') ```
Example: ```bash GET /one-drive/v1.0/me/drive/root/search(q='budget') ```
### Create Folder
```bash POST /one-drive/v1.0/me/drive/root/children Content-Type: application/json
{ "name": "New Folder", "folder": {}, "@microsoft.graph.conflictBehavior": "rename" } ```
在另一个文件夹内创建文件夹： ```bash POST /one-drive/v1.0/me/drive/items/{parent-id}/children Content-Type: application/json
{ "name": "Subfolder", "folder": {} } ```
### Upload File (Simple - up to 4MB)
```bash PUT /one-drive/v1.0/me/drive/items/{parent-id}:/{filename}:/content Content-Type: application/octet-stream
{file binary content} ```
Example - upload to root: ```bash PUT /one-drive/v1.0/me/drive/root:/document.txt:/content Content-Type: text/plain
Hello, OneDrive! ```
### Upload File (Large - resumable)
对于超过 4MB 的文件，请使用可恢复上传：
**Step 1: Create upload session** ```bash POST /one-drive/v1.0/me/drive/root:/{filename}:/createUploadSession Content-Type: application/json
{ "item": { "@microsoft.graph.conflictBehavior": "rename" } } ```
**Response:** ```json { "uploadUrl": "https://sn3302.up.1drv.com/up/...", "expirationDateTime": "2024-02-08T10:00:00Z" } ```
**Step 2: Upload bytes to the uploadUrl**
### Download File
获取文件元数据以检索下载 URL：
```bash GET /one-drive/v1.0/me/drive/items/{item-id} ```
响应包含 `@microsoft.graph.downloadUrl` - 一个在短时间内有效的预认证 URL：
```json { "id": "...", "name": "document.pdf", "@microsoft.graph.downloadUrl": "https://public-sn3302.files.1drv.com/..." } ```
直接使用此 URL 下载文件内容（无需 auth 请求头）。
### Update Item (Rename/Move)
```bash PATCH /one-drive/v1.0/me/drive/items/{item-id} Content-Type: application/json
{ "name": "new-name.txt" } ```
移动到不同的文件夹： ```bash PATCH /one-drive/v1.0/me/drive/items/{item-id} Content-Type: application/json
{ "parentReference": { "id": "{new-parent-id}" } } ```
### Copy Item
```bash POST /one-drive/v1.0/me/drive/items/{item-id}/copy Content-Type: application/json
{ "parentReference": { "id": "{destination-folder-id}" }, "name": "copied-file.txt" } ```
返回 `202 Accepted` 以及一个用于监控复制操作的 `Location` 请求头。
### Delete Item
```bash DELETE /one-drive/v1.0/me/drive/items/{item-id} ```
成功时返回 `204 No Content`。
### Sharing
#### Create Sharing Link
```bash POST /one-drive/v1.0/me/drive/items/{item-id}/createLink Content-Type: application/json
{ "type": "view", "scope": "anonymous" } ```
Link types: - `view` - 只读访问 - `edit` - 读写访问 - `embed` - 可嵌入链接
Scopes: - `anonymous` - 任何拥有链接的人 - `organization` - 您组织中的任何人
**Response:** ```json { "id": "...", "link": { "type": "view", "scope": "anonymous", "webUrl": "https://1drv.ms/b/..." } } ```
#### Invite Users (Share with specific people)
```bash POST /one-drive/v1.0/me/drive/items/{item-id}/invite Content-Type: application/json
{ "recipients": [ {"email": "[email protected]"} ], "roles": ["read"], "sendInvitation": true, "message": "Check out this file!" } ```
## Query Parameters
使用 OData 查询参数自定义响应：
- `$select` - 选择特定属性：`?$select=id,name,size` - `$expand` - 包含相关资源：`?$expand=children` - `$filter` - 筛选结果：`?$filter=file ne null`（仅文件） - `$orderby` - 排序结果：`?$orderby=name` - `$top` - 限制结果：`?$top=10`
Example: ```bash GET /one-drive/v1.0/me/drive/root/children?$select=id,name,size&$top=20&$orderby=name ```
## Pagination
结果已分页。响应包含用于附加页面的 `@odata.nextLink`：
```json { "value": [...], "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/root/children?$skiptoken=..." } ```
使用 `@odata.nextLink` 中的完整 URL（不带网关前缀）来获取下一页。
## Code Examples
### JavaScript
```javascript // List files in root const response = await fetch( 'https://gateway.maton.ai/one-drive/v1.0/me/drive/root/children', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json();
// Upload a file const uploadResponse = await fetch( 'https://gateway.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
```python import os import requests
# List files in root response = requests.get( 'https://gateway.maton.ai/one-drive/v1.0/me/drive/root/children', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) files = response.json()
# Upload a file upload_response = requests.put( 'https://gateway.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!' ) ```
## Notes
- OneDrive 使用 Microsoft Graph API (`graph.microsoft.com`) - 项目 ID 在驱动器内是唯一的 - 使用冒号（`:`）语法进行基于路径的寻址：`/root:/path/to/file` - 简单上传限制为 4MB；较大的文件请使用可恢复上传 - 来自 `@microsoft.graph.downloadUrl` 的下载 URL 是预认证且临时的 - 冲突行为选项：`fail`、`replace`、`rename` - 重要：使用 curl 命令时，当 URL 包含方括号时，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，`$MATON_API_KEY` 等环境变量在某些 shell 环境中可能无法正确展开
## Error Handling
| Status | Meaning | |--------|---------| | 400 | 缺少 OneDrive 连接或请求无效 | | 401 | Maton API 密钥无效或缺失 | | 403 | 权限不足 | | 404 | 项目未找到 | | 409 | 冲突（例如，项目已存在） | | 429 | 速率受限（检查 `Retry-After` 请求头） | | 4xx/5xx | 来自 Microsoft Graph API 的透传错误 |
### Error Response Format
```json { "error": { "code": "itemNotFound", "message": "The resource could not be found." } } ```
### 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 路径以 `one-drive` 开头。例如：
- 正确：`https://gateway.maton.ai/one-drive/v1.0/me/drive/root/children` - 错误：`https://gateway.maton.ai/v1.0/me/drive/root/children`
## Resources
- [OneDrive Developer Documentation](https://learn.microsoft.com/en-us/onedrive/developer/) - [Microsoft Graph API Reference](https://learn.microsoft.com/en-us/graph/api/overview) - [DriveItem Resource](https://learn.microsoft.com/en-us/graph/api/resources/driveitem) - [Drive Resource](https://learn.microsoft.com/en-us/graph/api/resources/drive) - [Sharing and Permissions](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/concepts/sharing) - [Large File Upload](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])