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

Bitzsoft.Integrations.CloudDrive.Microsoft365

Microsoft 365 企业网盘服务实现，基于 Microsoft Graph API v1.0 覆盖 OneDrive / SharePoint 文件操作。

功能

• 支持 OneDrive 个人版及 SharePoint 文档库
• OAuth 2.0 客户端凭据流认证，令牌自动缓存与刷新
• 小文件直接上传（< 4MB），大文件分块上传会话（最大 250GB）
• 文件/文件夹的增删改查、搜索、共享链接、权限管理、版本管理

安装

dotnet add package Bitzsoft.Integrations.CloudDrive.Microsoft365

<PackageReference Include="Bitzsoft.Integrations.CloudDrive.Microsoft365" Version="*" />

配置

appsettings.json

{
  "CloudDrive": {
    "Microsoft365": {
      "TenantId": "your-tenant-id",
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "AuthorityUrl": "",
      "HttpClientName": "Microsoft365CloudDrive",
      "LargeFileThreshold": 4194304
    }
  }
}

配置参数

Azure AD 应用注册

1. 登录 Azure Portal → Azure Active Directory → App registrations
2. 新建应用注册，记录 Application (client) ID 和 Directory (tenant) ID
3. 在 Certificates & secrets 中创建客户端密钥，记录密钥值
4. 在 API permissions 中添加 Microsoft Graph Application permissions：
   • Files.ReadWrite.All — 文件读写
   • Sites.ReadWrite.All — SharePoint 站点读写（可选）

注册

// 方式一：Action 配置
services.AddBitzsoftMicrosoft365CloudDrive(options =>
{
    options.TenantId = "your-tenant-id";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
});

// 方式二：IConfiguration 绑定
services.AddBitzsoftMicrosoft365CloudDrive(configuration, "CloudDrive:Microsoft365");

第三方请求日志

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftMicrosoft365CloudDrive(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;            // 单条正文截断上限
    opts.SensitiveFields.Add("mySecret"); // 额外脱敏字段
});
services.AddBitzsoftMicrosoft365CloudDrive(options => { /* ... */ });

使用示例

public class MyService
{
    private readonly ICloudDriveProvider _drive;

    public MyService(ICloudDriveProvider drive) => _drive = drive;

    public async Task UploadAsync(Stream fileStream, string fileName)
    {
        var result = await _drive.UploadAsync(new UploadFileRequest
        {
            FolderId = "root",
            FileName = fileName,
            Content = fileStream,
            ContentLength = fileStream.Length
        });

        Console.WriteLine($"上传成功: {result.FileInfo.Id}");
    }
}

Graph API 功能矩阵

OAuth 2.0 注意事项

• 使用 客户端凭据流（client_credentials），适用于服务端无用户交互场景
• 令牌默认缓存，过期前 5 分钟自动刷新
• 收到 401 响应时自动重试一次令牌刷新
• 如需访问特定用户 OneDrive，需使用 委托权限流 并传入用户 access token

注意事项

• Graph API 单次请求大小上限 4MB，超过需使用上传会话
• 上传会话最大支持 250GB，分块推荐 4MB
• CopyFileAsync 是异步操作，返回时不保证复制已完成
• SharePoint 文档库操作使用相同的 Graph API，通过站点/列表 ID 区分

依赖

• Bitzsoft.Integrations.CloudDrive，企业网盘抽象层
• Bitzsoft.Integrations.Compatibility，基础工具库

相关包