microsoft-onedrive

通过 curl + jq 操作 OneDrive / SharePoint 的 Microsoft Graph。用户的 OAuth 持有者令牌位于 $MICROSOFT_ONEDRIVE_TOKEN；每次调用都需要在 Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN 中携带该令牌。该令牌已包含用户在安装时同意的 OneDrive 权限范围（Files.Read、Files.Read.All，以及可选的 Files.ReadWrite.All、Sites.Read.All）。

Graph API 返回标准 JSON；失败时会返回 JSON {"error": {"code": "...", "message": "..."}} —— 将该错误原样展示给用户。

始终从 /me 开始，以确认连接正常，并了解当前操作所针对的账户 / 驱动器。

操作示例

验证身份验证（始终首先运行）

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  https://graph.microsoft.com/v1.0/me \
  | jq '{displayName, mail, userPrincipalName}'

如果收到 401 InvalidAuthenticationToken，则令牌已过期——请告知用户；用户需要重新安装连接器。

列出根目录中的文件

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/root/children?\$top=20&\$select=id,name,size,lastModifiedDateTime,folder,file" \
  | jq '.value[] | {id, name, size, kind: (if .folder then "folder" else .file.mimeType end), modified: .lastModifiedDateTime}'

文件夹包含 "folder":{"childCount":N}，文件包含 "file":{"mimeType":"..."}。

按路径列出子文件夹中的文件

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/root:/Documents:/children?\$top=20&\$select=id,name,size,lastModifiedDateTime"

路径使用 : 作为路径 / 段分隔符——:/Documents/Q1:/children。

搜索文件（递归）

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  --data-urlencode "q=quarterly report" --get \
  "https://graph.microsoft.com/v1.0/me/drive/root/search(q='quarterly report')?\$top=25&\$select=id,name,size,webUrl,lastModifiedDateTime"

search(q='') 使用空查询会返回 400。若要在没有关键词的情况下查找特定类型的文件，请按扩展名搜索：search(q='.pdf')。

最近修改的文件（跨文件夹）

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/recent?\$top=25" \
  | jq '.value[] | {name, modified: .lastModifiedDateTime, parent: .parentReference.path}'

与我共享的文件

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/sharedWithMe?\$top=25" \
  | jq '.value[] | {name, size: .size, owner: .remoteItem.shared.owner.user.displayName}'

按项目 ID 下载文件

# /content returns 302 to a pre-signed URL — let curl follow it.
curl -sSL -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/items/${ITEM_ID}/content" \
  -o "$SKILL_DIR/tmp/$(basename "$NAME")"

按路径下载文件

# URL-encode each path segment with jq -Rr @uri (or use printf encoding).
ENCODED=$(printf '%s' "Documents/report.docx" | jq -sRr @uri)
curl -sSL -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/root:/${ENCODED}:/content" \
  -o report.docx

上传小文件（< 4 MB）

curl -sS -X PUT \
  -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @/tmp/report.pdf \
  "https://graph.microsoft.com/v1.0/me/drive/root:/Documents/report.pdf:/content"

对于 > 4 MB 的文件，请使用上传会话（分块上传）：

# 1) create session
SESSION=$(curl -sS -X POST \
  -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"item":{"@microsoft.graph.conflictBehavior":"rename"}}' \
  "https://graph.microsoft.com/v1.0/me/drive/root:/Documents/big.zip:/createUploadSession")
UPLOAD_URL=$(echo "$SESSION" | jq -r .uploadUrl)
# 2) PUT in 10 MiB chunks with Content-Range: bytes <start>-<end>/<total>
# (See Microsoft Graph docs for the chunking loop; jq + dd makes this trivial.)

创建文件夹

curl -sS -X POST \
  -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reports","folder":{},"@microsoft.graph.conflictBehavior":"rename"}' \
  https://graph.microsoft.com/v1.0/me/drive/root/children

@microsoft.graph.conflictBehavior：rename（自动添加后缀）、replace（覆盖）、fail（若已存在则报错）。默认值为 fail。

重命名 / 移动（PATCH）

⚠️ 执行前始终向用户展示源位置和目标位置。

# Rename only
curl -sS -X PATCH \
  -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"renamed.docx"}' \
  "https://graph.microsoft.com/v1.0/me/drive/items/${ITEM_ID}"

# Move to a different folder
curl -sS -X PATCH \
  -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg pid "$NEW_PARENT_ID" '{parentReference:{id:$pid}}')" \
  "https://graph.microsoft.com/v1.0/me/drive/items/${ITEM_ID}"

删除

⚠️ 始终先获取项目名称，并与用户确认。

# 1) Show what will be deleted
curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/items/${ITEM_ID}?\$select=name,size,lastModifiedDateTime" \
  | jq '"Delete \(.name) (\(.size) bytes, modified \(.lastModifiedDateTime))?"'

# 2) After user confirms (returns 204 No Content)
curl -sS -X DELETE -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/drive/items/${ITEM_ID}" \
  -w "HTTP %{http_code}\n"

创建共享链接

⚠️ 共享前务必与用户确认——这会将数据暴露给外部。

curl -sS -X POST \
  -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"view","scope":"organization"}' \
  "https://graph.microsoft.com/v1.0/me/drive/items/${ITEM_ID}/createLink" \
  | jq '.link.webUrl'

type：view | edit | embed。scope：anonymous | organization | users。

列出 SharePoint 站点

需要 Sites.Read.All。

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/sites?search=*&\$top=10" \
  | jq '.value[] | {id, name: .displayName, webUrl}'

站点中的文件：

curl -sS -H "Authorization: Bearer $MICROSOFT_ONEDRIVE_TOKEN" \
  "https://graph.microsoft.com/v1.0/sites/${SITE_ID}/drive/root/children?\$top=20"

OData 速查

参数	示例
$select	id,name,size,lastModifiedDateTime
$filter	name eq 'report.docx'、size gt 1000000
$orderby	lastModifiedDateTime desc
$top	浏览时为 10，搜索时为 25
$expand	children、permissions

使用 curl 时，配合 --data-urlencode "$key=$value" --get，以避免对 $ 和空格进行 shell 引号处理。

规则

• 始终传入 $select ——默认情况下，每个项目会返回 30 多个字段。
• 浏览时使用 $top=10，搜索时使用 25。除非用户要求，否则不要翻阅超过 50 个结果。
• 在路径中使用 ID 时对其进行 URL 编码 ——ID 可能包含 +、/、=。使用 jq -sRr @uri。
• 空的 search(q='') 会返回 400 ——没有关键词时，请按扩展名搜索。

关键：破坏性操作须征得用户同意

绝不在未获得明确确认的情况下删除、覆盖或共享。流程：准备 → 展示 → 执行。

操作	向用户展示的内容
删除	“删除‘{name}’（{size} 字节，修改于 {date}）？”
覆盖（@microsoft.graph.conflictBehavior=replace）	“覆盖‘{name}’？现有文件：{size}，修改于 {date}”
共享（createLink）	“为‘{name}’创建具有 {scope} 访问权限的 {type} 链接？”
移动	“将‘{name}’从 {old folder} 移动到 {new folder}？”
批量操作	数量 + 示例：“删除 /Reports/ 中的 12 个文件？”

错误

• 401 InvalidAuthenticationToken → 令牌已过期；用户必须重新安装连接器。
• 403 accessDenied → 缺少权限范围（例如，尝试使用只读令牌写入）；请用户重新安装，并勾选写入权限范围。
• 429 TooManyRequests → 遵循 Retry-After 标头（单位为秒）。
• 404 itemNotFound → ID 或路径错误；请仔细检查大小写。

参考

深入了解请参阅 Microsoft 文档：

• Drive 项：https://learn.microsoft.com/en-us/graph/api/resources/driveitem
• 上传大文件：https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession
• 共享：https://learn.microsoft.com/en-us/graph/api/driveitem-createlink