FeishuNetSdk 1.0.7

FeishuNetSdk

飞书开放平台网址：https://open.feishu.cn/

接口清单详见：TenantAccessToken适用接口清单-978个

用法：

1、安装Nuget包

2、依赖注册（直接输入应用凭证的方式，二选一）

builder.Services.AddHttpApi<IFeishuApi>();
builder.Services.AddHttpApi<IFeishuTenantApi>();
builder.Services.AddTokenProvider<IFeishuTenantApi>(async service =>
{
    //获取凭证接口
    var feishuApi = service.GetRequiredService<IFeishuApi>();
    //获取tenant_access_token
    var response = await feishuApi.PostAuthV3TenantAccessTokenInternalAsync(
            new FeishuNetSdk.Auth.Spec
                .PostAuthV3TenantAccessTokenInternalBodyDto
                {
                    //此处修改为自建的应用凭证Id和密钥
                    AppId = "cli_a5bf8739dab8d0c",
                    AppSecret = "vn7MjifCNm04dUlWBg6yWbijHvEpel6G"
                });
    //当返回码异常时，抛出`TokenException`异常
    if (response.Code != 0)
        throw new TokenException(response.Msg);
    //返回一个能自动缓存和过期重取的Token实例
    return new TokenResult
    {
        Access_token = response.TenantAccessToken,
        Expires_in = response.Expire
    };
});

2、依赖注册（配置文件的方式，二选一）

1. 创建FeishuOption类：

public record FeishuOption
{
    public string app_id { get; set; } = string.Empty;
    public string app_secret { get; set; } = string.Empty;
}

2. 在appsettings.json文件中添加配置：

"Feishu": {
    "app_id": "cli_a5bf8739dab8d0c",
    "app_secret": "vn7MjifCNm04dUlWBg6yWbijHvEpel6G",
}

3. 添加绑定配置：

builder.Services.Configure<FeishuOption>(builder.Configuration.GetSection("Feishu"));

4. 接口注册：

builder.Services.AddHttpApi<IFeishuApi>();
builder.Services.AddHttpApi<IFeishuTenantApi>();
builder.Services.AddTokenProvider<IFeishuTenantApi>(async service =>
{
    //获取配置
    var option = service.GetRequiredService<IOptionsMonitor<FeishuOption>>();
    //获取凭证接口
    var feishuApi = service.GetRequiredService<IFeishuApi>();
    //获取tenant_access_token
    var response = await feishuApi.PostAuthV3TenantAccessTokenInternalAsync(
            new FeishuNetSdk.Auth.Spec
                .PostAuthV3TenantAccessTokenInternalBodyDto
                {
                    AppId = option.CurrentValue.app_id,
                    AppSecret = option.CurrentValue.app_secret
                });
    //当返回码异常时，抛出`TokenException`异常
    if (response.Code != 0)
        throw new TokenException(response.Msg);
    //返回一个能自动缓存和过期重取的Token实例
    return new TokenResult
    {
        Access_token = response.TenantAccessToken,
        Expires_in = response.Expire
    };
});

3、依赖注入

public class TestController : ControllerBase
{
    private readonly IFeishuTenantApi _feishuApi;
    public TestController(IFeishuTenantApi feishuApi)
    {
        _feishuApi = feishuApi;
    }
}

4、方法调用

[HttpGet("t2")]
public async Task<IResult> GetT2Async()
{
    var result = await _feishuApi.GetImV1ChatsAsync();
    return Results.Json(result);
}

5、当获取凭证异常时，内部异常类型为TokenException（与接口注册时抛出的异常类型有关）。

try
{
    var result = await _feishuApi.GetEventV1OutboundIpAsync();
    return Results.Json(result);
}
catch (HttpRequestException ex) when (ex.InnerException is TokenException tokenException)
{
    return Results.Problem(tokenException.Message);
}

示例：

文件上传示例

参数 FormDataFile 支持 filePath、FileInfo、byte[]、Stream。

需要注意部分接口注释上有关于文件格式限制的说明。

[HttpGet("t3")]
public async Task<IResult> GetT3Async()
{
    //定义文件存储路径
    var filePath = @"D:\Users\Downloads\e9bd937f1d7a4c4f992724f5de44bb14.jpg";
    //调用接口
    var result = await _feishuApi.PostImV1ImagesAsync(
        new FeishuNetSdk.Im.PostImV1ImagesBodyDto
        {
            ImageType = "message"
        },
        new FormDataFile(filePath));
    //当返回码异常时，返回错误消息
    if (!result.IsSuccess)
        return Results.Problem(result.Msg);
    return Results.Json(result);
}

文件下载示例

下载操作默认返回HttpResponseMessage，由于没有返回码（code）可以判断操作是否成功，所以建议配合 EnsureSuccessStatusCode() 方法使用，当响应状态码异常时，会抛出异常，需要自行捕获处理。

[HttpGet("t4")]
public async Task<IResult> GetT4Async()
{
    //定义文件存储路径
    var filePath = @"D:\Users\Downloads\e9bd937f----1.jpg";
    //调用接口
    var result = (await _feishuApi.GetImV1ImagesByImageKeyAsync(
        image_key: "img_xxxx-fbdc-4c36-b17c-ac8aa1aee7dg"))
        //当响应状态码异常时，会抛出异常，需要自行捕获处理
        .EnsureSuccessStatusCode();

    //保存文件到指定路径
    await result.SaveAsAsync(filePath);
    return Results.Json(result);
}

个别接口支持部分下载，可以按需设置参数range，字符串格式为bytes=0-100表示下载第0字节到第100字节的数据，默认不填或者null表示下载整个文件。示例如下：

[HttpGet("t5")]
public async Task<IResult> GetT5Async()
{
    //定义文件存储路径
    var filePath = @"D:\Users\Downloads\e9bd937f----2.jpg";
    //调用接口
    var result = (await _feishuApi.GetDriveV1MediasByFileTokenDownloadAsync(
        file_token: "OQBpbF8AEoZ0gqxpCMwcRPWFn8c",
        range: "bytes=0-100"))
        //当响应状态码异常时，会抛出异常，需要自行捕获处理
        .EnsureSuccessStatusCode();

    //保存到指定路径，可能只是文件的一部分，并非完整。
    await result.SaveAsAsync(filePath);
    return Results.Json(result);
}

注意事项：

云文档操作

文档操作前提需要有编辑权限，步骤如下：

1. 为自建应用添加机器人能力。
2. 将应用机器人加入或创建一个新群组。
3. 进入目标文档，将该群组设置为文档协作者。
4. 调用接口方法。

以下是仅在特殊情况下使用的特殊方法。

接口重载/覆盖

1. 新建API，继承于 IFeishuTenantApi。
2. 使用重载/覆盖方法

如果要覆盖方法，比如是在保持参数完全一致的情况下，修改http地址，需要在方法前加 new （参数不一致是重载，重载不用加new ），然后将新地址更换到属性上。更换http方法、返回参数及其他属性也是同理。

1、新建API

public interface INewApi : IFeishuTenantApi
{
    [HttpGet("/open-apis/event/v1/outbound_ip1")]
    new System.Threading.Tasks.Task<HttpResponseMessage> GetEventV1OutboundIpAsync();
}

2、新增依赖注册

builder.Services.AddHttpApi<INewApi>();

3、修改依赖注入

public class TestController : ControllerBase
{
    //此处更改为新的API：INewApi
    private readonly INewApi _feishuApi;
    public TestController(INewApi feishuApi)
    {
        _feishuApi = feishuApi;
    }
}

启用状态异常错误

默认：关闭

飞书接口在返回结果异常时，同时会返回状态异常，状态异常通常无法实质判断异常原因，具体原因会在返回结果中提示。所以接口默认忽略状态异常，开启方法如下：

1. 新建API，继承于 IFeishuTenantApi。
2. 添加接口属性 IgnoreStatusExceptionFilter 并将属性 Enable 设置为 false ，意为停用忽略，即启用异常提示。
3. 参照上述使用新接口进行方法调用。

[IgnoreStatusExceptionFilter(Enable = false)]
public interface INewApi : IFeishuTenantApi
{ }

开启状态异常之后进行捕获，内部异常为ApiResponseStatusException：

try
{
    var result = await _feishuApi.GetEventV1OutboundIpAsync();
    return Results.Json(result);
}
catch (HttpRequestException ex) when (ex.InnerException is ApiResponseStatusException statusException)
{
    // 响应状态码异常
    return Results.Problem(statusException.Message);
}

关闭接口日志

默认：开启

1. 新建API，继承于 IFeishuTenantApi。
2. 添加接口属性 LoggingFilter 并设置属性 Enable 为 false ，即可停用日志。
3. 参照上述使用新接口进行方法调用。
4. LoggingFilter 和 IgnoreStatusExceptionFilter 可以同时存在。

[LoggingFilter(Enable = false), IgnoreStatusExceptionFilter(Enable = false)]
public interface INewApi : IFeishuTenantApi
{ }

需要注意： IFeishuApi 和 IFeishuTenantApi 各有独立的 LoggingFilter 与 IgnoreStatusExceptionFilter 属性，若想全部关闭，需要分别继承接口并将属性 Enable 设置为 false 。

启用缓存

默认：关闭

缓存属性Cache，在接口上使用表示对接口内所有方法启用，建议仅针对具体方法使用，在单个方法上增加属性即可。数值单位是毫秒。

public interface INewApi : IFeishuTenantApi
{
    [Cache(10 * 1000)]
    [HttpGet("/open-apis/event/v1/outbound_ip1")]
    new System.Threading.Tasks.Task<HttpResponseMessage> GetEventV1OutboundIpAsync();
}