Bitzsoft.Integrations.CloudDrive.Microsoft365 1.0.0-alpha.10

Bitzsoft.Integrations.CloudDrive.Microsoft365

面向既有 ICloudDriveProvider 的 Microsoft 365 OneDrive / SharePoint 兼容 Adapter，支持 net5.0、net8.0 与 net10.0。新建的多租户、增量同步或 精确 continuation 场景应优先直接使用 Bitzsoft.Integrations.MicrosoftGraph。

关键行为

• 使用 OAuth 2.0 client credentials 和共享 Microsoft Graph / REST transport； 不再维护第二套令牌缓存与 HttpClient。
• 应用凭据不能使用 /me/drive，因此必须显式配置 DriveId；所有请求实际发送到 /drives/{driveId}。
• 小文件正文直接从调用方流发送；大文件只保留一个 5 MiB 分片，不会把最高 250 GB 的内容整体读入内存。
• 非末分片固定为 5 MiB = 16 × 320 KiB，满足 Graph 的分片对齐要求。
• Graph OAuth 只发送到 Graph origin；下载重定向和上传会话 URL 经过 SSRF allow-list 后匿名访问，不携带 Authorization 或 Cookie。
• 下载返回流拥有 HTTP response；释放返回流会同时释放 response 和连接 lease。
• 协议层不限制响应正文或下载大小。兆级第三方响应会被完整读取或流式返回， 不设置强制截断上限。
• Graph 错误转换为 CloudDriveException 时不复制供应商原始正文，避免敏感内容 进入日志和异常文本。

能力与兼容边界

CopyFileAsync 会在发网前抛出 NotSupportedException，不会再把源文件元数据 伪装成复制结果。ListFilesAsync 和 SearchAsync 仅接受 pageIndex = 1； 响应仍保留 NextPageToken 作为存在后续页的证据。需要完整分页、delta、多 drive 或多租户时，请使用 typed Microsoft Graph client。

链接的 upload-only/download-only、密码、过期时间、最大访问次数以及 invite 的 owner 角色也会明确拒绝，不会静默降级成权限更宽或语义不同的 Graph 请求。

安装

dotnet add package Bitzsoft.Integrations.CloudDrive.Microsoft365

配置

{
  "CloudDrive": {
    "Microsoft365": {
      "TenantId": "00000000-0000-0000-0000-000000000000",
      "ClientId": "11111111-1111-1111-1111-111111111111",
      "ClientSecret": "store-this-in-a-secret-provider",
      "DriveId": "b!configured-drive-id",
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "AuthorityUrl": "",
      "LargeFileThreshold": 4194304
    }
  }
}

应用至少需要与实际操作相符的 Microsoft Graph Application permission，例如 Files.ReadWrite.All 或 SharePoint 场景的 Sites.ReadWrite.All，并完成管理员 同意。drive ID 应通过管理员控制的站点/drive 发现流程取得；client credentials 不能以 /me/drive 代替。

注册

从默认配置节绑定：

builder.Services.AddBitzsoftMicrosoft365CloudDrive(
    builder.Configuration);

使用自定义配置节：

builder.Services.AddBitzsoftMicrosoft365CloudDrive(
    builder.Configuration,
    "Integrations:MicrosoftDrive");

或使用委托：

builder.Services.AddBitzsoftMicrosoft365CloudDrive(options =>
{
    options.TenantId = tenantId;
    options.ClientId = clientId;
    options.ClientSecret = clientSecret;
    options.DriveId = driveId;
});

该注册只增加兼容 Provider 与共享 Graph transport factory，不会额外注册一个全局 IMicrosoftGraphClient、端点解析器或凭据解析器，因此不会覆盖宿主已有的多租户 Graph 配置。

上传语义

await using var stream = File.OpenRead("report.pdf");
var result = await drive.UploadAsync(
    new UploadFileRequest
    {
        FolderId = "root",
        FileName = "report.pdf",
        Content = stream,
        ContentLength = stream.Length,
        ContentType = "application/pdf",
        ConflictBehavior = "rename"
    });

• Adapter 不释放调用方的 Content。
• 可定位流未填写 ContentLength 时，从当前位置到末尾自动计算。
• 可定位流同时填写 ContentLength 时，声明值必须与剩余长度完全一致。
• 非可定位流必须填写 ContentLength，否则在发网前失败。
• 上传期间若流提前结束，会抛出 content_ended_early，不会把不完整内容报告为成功。
• 最大声明长度为 250 GB；最后一个分片必须返回已完成的 driveItem。

下载语义

await using var content = await drive.DownloadAsync(fileId);
await content.CopyToAsync(destination);

必须释放下载流。下载正文不做应用层缓冲或大小截断；取消令牌控制响应头和正文读取， 并不改变内容保留策略。

RequestLogging 策略

本 Adapter 和 Microsoft Graph 协议层都不设置日志正文上限。若宿主在外围管道使用 Bitzsoft.Integrations.RequestLogging：

• MaxLoggedBodyLength = null 为默认值，表示完整记录，包括兆级 response；
• MaxInMemoryBodyBytes 只决定何时切换到加密临时文件，不会截断正文；
• 只有宿主明确设置正数 MaxLoggedBodyLength 时才截断。

因此，第三方 response 设计不合理而达到兆级时，不会被连接器强制丢弃；容量治理由 宿主的日志存储策略显式决定。文件下载和上传会话 bearer URL 不应记录正文或 URL。

国家云与代理

可通过 BaseUrl 和精确的 AuthorityUrl 使用 Microsoft 365 全球云、中国世纪互联、 美国政府云或受控 HTTPS 代理。OAuth audience 从 Graph service root 的 origin 推导。 下载/上传的预认证 URL 仅允许 Microsoft 官方 OneDrive/SharePoint 域名或所配置 Graph origin，其他目标会在发网前拒绝。

官方协议依据

• Get drive
• List children
• Create upload session
• Copy driveItem

依赖