Bitzsoft.Integrations.IManage 1.0.0-alpha.7

Bitzsoft.Integrations.IManage

iManage Work 文档管理集成客户端 — REST API v2 封装、OAuth2 认证、多租户 Token 刷新。

功能特性

• 全功能 API 覆盖 — 聚合库、工作区、文件夹、Tab、文档、用户、用户组、搜索、自定义字段、安全 ACL、法律保留、分享、审计、扩展元数据共 14 个模块
• 多租户支持 — 通过 IIManageOptionsProvider 按租户动态解析配置，IIManageClientFactory.Create(tenantId) 创建租户隔离的客户端
• 自动 Token 管理 — IManageAuthHandler 自动注入 Bearer Token，401 时刷新重试，Token 持久化由宿主实现 IIManageTokenStore
• 流式分页 — StreamWorkspacesAsync、StreamSearchAsync<T> 等方法基于 IAsyncEnumerable，内存占用恒定
• Resilience 管道 — 内置标准重试与熔断策略（AddStandardResilienceHandler）
• 文档全生命周期 — 上传、下载、版本管理、检入/检出、复制/移动、安全 ACL、扩展元数据
• 第三方请求日志 — 内置 RequestLogging DelegatingHandler，记录所有出站 HTTP 请求与响应，便于问题排查
• 结构化异常 — IManageException 携带 IManageErrorCode、HTTP 状态码、API 错误码和请求 URL

安装

dotnet add package Bitzsoft.Integrations.IManage

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

配置

{
  "IManage": {
    "Host": "https://imanage.example.com",
    "ClientId": "{{IMANAGE_CLIENT_ID}}",
    "ClientSecret": "{{IMANAGE_CLIENT_SECRET}}",
    "DefaultCustomerId": "1",
    "DefaultLibraryId": "ACTIVE",
    "DefaultTemplateId": "ACTIVE!339828",
    "TimeoutMs": 30000,
    "TokenEndpoint": "/auth/oauth2/token",
    "ApiBasePath": "/work/api/v2",
    "TokenCacheMinutes": 30,
    "DefaultSecurity": "public",
    "DefaultPageSize": 100,
    "WorkspaceChildrenLimit": 300
  }
}

使用 Resource Owner Password Credentials 模式时，额外配置 UserName 和 Password。

注册服务

using Bitzsoft.Integrations.IManage;

// 基本注册（单租户）
services.AddTNTIManage(options =>
{
    options.Host = "https://imanage.example.com";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.DefaultLibraryId = "ACTIVE";
});

// 必须注册 IIManageTokenStore 实现（如 Redis、Memory 等）
services.AddSingleton<IIManageTokenStore, RedisIManageTokenStore>();

// 多租户场景：不传 configure，注册自定义 IIManageOptionsProvider
services.AddTNTIManage();
services.AddSingleton<IIManageOptionsProvider, TenantIManageOptionsProvider>();
services.AddSingleton<IIManageTokenStore, RedisIManageTokenStore>();

第三方请求日志

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

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

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("mySecret");
});
services.AddTNTIManage(options => { /* ... */ });

使用示例

搜索工作区

using Bitzsoft.Integrations.IManage;

public class WorkspaceService
{
    private readonly IIManageClientFactory _factory;

    public WorkspaceService(IIManageClientFactory factory)
    {
        _factory = factory;
    }

    public async Task<List<WorkspaceResponse>> SearchAsync(string keyword, CancellationToken ct)
    {
        using var client = _factory.Create();

        // 单页搜索
        var result = await client.SearchWorkspacesAsync(
            new SearchWorkspaceInput { Name = keyword }, ct);

        return result.Data ?? [];
    }

    public async IAsyncEnumerable<WorkspaceResponse> StreamAllAsync(
        string keyword, [EnumeratorCancellation] CancellationToken ct)
    {
        using var client = _factory.Create();

        // 流式搜索（自动分页，适合导出/同步）
        await foreach (var ws in client.StreamWorkspacesAsync(
            new SearchWorkspaceInput { Name = keyword }, ct))
        {
            yield return ws;
        }
    }
}

上传文档

using Bitzsoft.Integrations.IManage;

using var client = _factory.Create();

// 上传文件到指定文件夹
var uploadInput = new UploadDocumentInput
{
    Name = "合同草案.pdf",
    DocProfile = new DocProfile
    {
        // 填充文档元数据（custom1, custom2, class 等）
    }
};

await using var fileStream = File.OpenRead("/path/to/contract.pdf");
var document = await client.UploadDocumentAsync(
    folderId: "ACTIVE!453.1",
    input: uploadInput,
    fileStream: fileStream);

Console.WriteLine($"文档已上传: {document.Id}");

搜索文档

using Bitzsoft.Integrations.IManage;

using var client = _factory.Create();

// 使用搜索 API 查询文档
var searchRequest = new SearchRequest
{
    Query = "合同 AND 2024",
    SearchType = "document",
    SortOrder = "desc",
    StartIndex = 0,
    MaxResults = 50
};

// 流式搜索（自动分页）
await foreach (var doc in client.StreamSearchAsync<DocumentResponse>(searchRequest))
{
    Console.WriteLine($"文档: {doc.Id} - {doc.Name}");
}

// 下载文档
await using var content = await client.DownloadDocumentAsync("ACTIVE!98765.1");
await using var output = File.Create("downloaded.pdf");
await content.CopyToAsync(output);

多租户使用

using Bitzsoft.Integrations.IManage;

// 通过工厂创建指定租户的客户端
using var client = _factory.Create(tenantId: "tenant-001");

var workspace = await client.GetWorkspaceAsync("ACTIVE!123456");

相关包