Microsoft OneDrive

2026-03-27 新闻来源：网淘吧围观:23

电脑广告

手机广告

OneDrive

通过 Microsoft Graph 使用托管的 OAuth 认证访问 OneDrive API。通过完整的 CRUD（创建、读取、更新、删除）操作管理文件、文件夹、驱动器和共享。

快速开始

# 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

基础 URL

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

网关将请求代理到graph.microsoft.com并自动注入您的 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 密钥

连接管理请在.

列出连接

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

创建连接

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

获取连接

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

在浏览器中打开返回的网址以完成 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

指定连接

如果你有多个 OneDrive 连接，请使用Maton-Connection标头来指定要使用哪一个：

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

驱动器

获取当前用户的驱动器

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

响应：

{
  "id": "b!F3Y7M0VT80OO9iu_D6Z-LA...",
  "driveType": "personal",
  "name": "OneDrive",
  "owner": {
    "user": {
      "displayName": "John Doe",
      "id": "d4648f06c91d9d3d"
    }
  },
  "quota": {
    "total": 5368709120,
    "used": 1234567,
    "remaining": 5367474553
  }
}

列出用户的驱动器

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

按 ID 获取驱动器

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

文件和文件夹

获取驱动器根目录

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

列出根目录子项

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

响应：

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

按ID获取项目

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

按路径获取项目

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

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

按路径列出文件夹子项

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

获取项目子项

GET /one-drive/v1.0/me/drive/items/{item-id}/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

搜索

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

示例：

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

创建文件夹

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

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

在另一个文件夹内创建文件夹：

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

{
  "name": "Subfolder",
  "folder": {}
}

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

PUT /one-drive/v1.0/me/drive/items/{parent-id}:/{filename}:/content
Content-Type: application/octet-stream

{file binary content}

示例 - 上传至根目录：

PUT /one-drive/v1.0/me/drive/root:/document.txt:/content
Content-Type: text/plain

Hello, OneDrive!

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

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

步骤1：创建上传会话

POST /one-drive/v1.0/me/drive/root:/{filename}:/createUploadSession
Content-Type: application/json

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

响应：

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

步骤2：将字节上传至uploadUrl

下载文件

获取文件元数据以检索下载URL：

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

响应包含@microsoft.graph.downloadUrl- 一个预认证的URL，短期内有效：

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

直接使用此URL下载文件内容（无需认证头）。

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

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

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

移动到不同文件夹：

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

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

返回202 已接受并包含一个位置头部，用于监控复制操作。

删除项目

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

返回204 无内容表示操作成功。

共享

创建共享链接

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

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

链接类型：

查看- 只读访问权限
编辑- 读写权限
嵌入- 可嵌入链接

范围：

匿名- 任何拥有链接的人
组织- 您组织内的任何人

响应：

{
  "id": "...",
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/b/..."
  }
}

邀请用户（与特定人员共享）

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

查询参数

使用 OData 查询参数自定义响应：

$select- 选择特定属性：?$select=id,name,size
$expand- 包含相关资源：?$expand=children
$filter- 筛选结果：?$filter=file ne null（仅文件）
$orderby- 排序结果：?$orderby=name
$top- 限制结果数量：?$top=10

示例：

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

分页

结果采用分页形式。响应中包含@odata.nextLink用于获取后续页面：

{
  "value": [...],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/root/children?$skiptoken=..."
}

使用来自@odata.nextLink的完整URL（不含网关前缀）来获取下一页。

代码示例

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

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

注意事项

OneDrive使用Microsoft Graph API (graph.microsoft.com)
项目ID在驱动器内是唯一的
使用冒号 (:) 语法进行基于路径的寻址：/root:/path/to/file
简单上传限制为4MB；对于更大的文件，请使用可恢复上传
下载URL来自@microsoft.graph.downloadUrl是预先认证且临时的
冲突行为选项：失败、替换、重命名
重要提示：使用curl命令时，当URL包含括号时，请使用curl -g以禁用通配符解析
重要提示：当通过管道将curl输出传递到jq或其他命令时，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开

错误处理

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

错误响应格式

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

故障排除：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路径以one-drive开头。例如：

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

资源

免责申明

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

打赏

文章底部电脑广告

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

标签

上一篇：Global Macro Database Assistant 下一篇：Web Deploy GitHub Pages

Microsoft OneDrive

OneDrive

快速开始

基础 URL

认证

获取您的 API 密钥

复制您的 API 密钥

列出连接

创建连接

获取连接

删除连接

指定连接

API 参考

驱动器

获取当前用户的驱动器

列出用户的驱动器

按 ID 获取驱动器

文件和文件夹

获取驱动器根目录

列出根目录子项

按ID获取项目

按路径获取项目

按路径列出文件夹子项

获取项目子项

特殊文件夹

最近与共享

获取最近文件

获取与我共享的文件

搜索

创建文件夹

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

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

下载文件

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

复制项目

删除项目

共享

创建共享链接

邀请用户（与特定人员共享）

查询参数

分页

代码示例

JavaScript

Python

注意事项

错误处理

错误响应格式

故障排除：API密钥问题

故障排除：无效的应用名称

资源

相关文章

推荐文章

热门浏览

标签列表