Skip to content
Bitzsoft.Integrationsbitzsoft.integrations

Reference

钉钉 TeamWork

钉钉协同办公包的 DingTalkOptions 配置字段、access_token 鉴权、6 个能力接口与使用示例。

Last updated

包信息

属性
NuGet 包Bitzsoft.Integrations.TeamWork.DingTalk
Provider IDdingtalk
鉴权方式access_token query 参数(DingTalkAuthHandler 自动注入)
能力接口Org、Message、Todo、Approval、Sso、Health(6 个)

配置字段(DingTalkOptions)

字段类型必填默认值说明
AppKeystring应用 AppKey
AppSecretstring应用 AppSecret
AgentIdlong工作通知必填0应用 AgentId
BaseUrlstringhttps://oapi.dingtalk.com旧版服务端 API 基地址
NewApiBaseUrlstringhttps://api.dingtalk.com新版 API 基地址(SSO 用)
LoginBaseUrlstringhttps://login.dingtalk.comOAuth2 扫码授权页
CallbackTokenstring?回调 Token
CallbackAesKeystring?回调加解密 AES Key
HttpClientNamestringTeamWorkDingTalk业务 HttpClient 命名
TokenHttpClientNamestringTeamWorkDingTalkToken令牌刷新专用 HttpClient

配置示例

{
"TeamWork": {
"DingTalk": {
"AppKey": "dingxxxxxxx",
"AppSecret": "your-app-secret",
"AgentId": 123456789,
"BaseUrl": "https://oapi.dingtalk.com",
"NewApiBaseUrl": "https://api.dingtalk.com",
"LoginBaseUrl": "https://login.dingtalk.com"
}
}
}

DI 注册

// ① 配置节绑定
builder.Services.AddBitzsoftDingTalkTeamWork(builder.Configuration.GetSection("TeamWork:DingTalk"));
// ② 委托配置
builder.Services.AddBitzsoftDingTalkTeamWork(options =>
{
options.AppKey = "dingxxxxxxx";
options.AppSecret = "your-app-secret";
options.AgentId = 123456789;
});

能力接口方法

ITeamWorkOrgProvider

Task<IReadOnlyList<DepartmentInfo>> GetDepartmentsAsync(long? parentId = null, CancellationToken ct = default);
Task<IReadOnlyList<EmployeeInfo>> GetEmployeesAsync(long departmentId, CancellationToken ct = default);

ITeamWorkMessageProvider

Task<MessageDeliveryResult> SendWorkNotificationAsync(WorkNotificationRequest request, CancellationToken ct = default);
Task<MessageDeliveryResult> SendCardMessageAsync(CardMessageRequest request, CancellationToken ct = default);

ITeamWorkTodoProvider

Task<string> CreateTodoAsync(TodoCreateRequest request, CancellationToken ct = default);
Task UpdateTodoStatusAsync(string todoId, TodoStatus status, CancellationToken ct = default);

ITeamWorkApprovalProvider

Task<string> StartApprovalAsync(ApprovalStartRequest request, CancellationToken ct = default);
Task<ApprovalStatus> GetApprovalStatusAsync(string processInstanceId, CancellationToken ct = default);

ITeamWorkSsoProvider

Task<string> GetAuthorizeUrlAsync(string redirectUri, string state, CancellationToken ct = default);
Task<SsoUserInfo> GetUserInfoAsync(string authCode, CancellationToken ct = default);

ITeamWorkHealthProvider

Task<TeamWorkHealthStatus> CheckHealthAsync(CancellationToken ct = default);

使用示例

public class NotificationService(ITeamWorkMessageProvider message)
{
public async Task PushAsync(string userId, string content)
{
await message.SendWorkNotificationAsync(new WorkNotificationRequest
{
ToUser = userId,
Content = content,
});
}
}

已知限制

  • 待办只支持标记完成UpdateTodoStatusAsync 实际只支持设为 Done,不支持撤回。
  • GetDepartmentsAsync 递归整棵子树:钉钉 /topapi/v2/department/listsub 只返回下一级,实现内部递归并做环形防护(HashSet<long> 去重)。
  • GetEmployeesAsync 分页上限:无”全公司用户”单接口,遍历各部门分页拉取,设安全上限 MaxUserListPages = 1000

相关

100%

滚轮或按钮缩放 · 放大后拖动画面 · 双击切换 100% / 200%