Galosys.Foundation.AlibabaCloud.Sdk.DingTalk 26.7.31.1

Galosys.Foundation.AlibabaCloud.Sdk.DingTalk

钉钉平台适配器，基于 AlibabaCloud.SDK.Dingtalk 2.2.54 实现。寄生命名空间 AlibabaCloud.SDK.Dingtalk。

消息发送使用企业机器人 API（robot_1_0），需要权限 qyapi_robot_sendmsg。机器人需提前添加到目标群或个人会话中。

1. 配置

appsettings.json：

{
  "DingTalk": {
    "AppKey": "your-app-key",
    "AppSecret": "your-app-secret",
    "RobotCode": "your-robot-code",
    "Alarm": {
      "RobotCode": "your-alarm-robot-code",
      "OpenConversationId": "chatxxx"
    }
  }
}

2. DI 注册

using AlibabaCloud.SDK.Dingtalk;

services.AddAlibabaCloudDingTalk();

3. 获取 Platform

var platform = serviceProvider.GetRequiredService<IImPlatform>();
// platform.Platform => "dingtalk"

4. 发送消息（企业机器人）

// 向用户发送单聊消息
var msgId = await platform.Notification.SendAsync(new ImMessage(
    ImTargetType.User,
    "manager123",           // 钉钉 userId
    ImMessageType.Text,
    "审批通知",
    "您有一笔采购单待审批，请及时处理。",
    null));

// 向群发送消息
var msgId = await platform.Notification.SendAsync(new ImMessage(
    ImTargetType.Group,
    "cidXXX",               // 群 OpenConversationId
    ImMessageType.Markdown,
    "库存预警",
    "**物料A** 库存低于安全库存，请及时补货。",
    null));

5. 发送交互卡片

var cardId = await platform.Notification.SendCardAsync("manager123",
    new ApprovalCardData(
        "采购审批单",
        15000m,
        "张三",
        "采购部门急用，请尽快审批",
        new[] { new ImAction("通过", "approve", ActionType.Callback) }
    ));

6. 撤销消息

var success = await platform.Notification.RevokeAsync(msgId);

7. 发起审批

var instanceId = await platform.Approval.StartAsync(new ApprovalRequest(
    BizKey: "PO-2024-001",
    Title: "服务器采购审批",
    Description: "申请采购 3 台 Dell 服务器",
    Amount: 150000m,
    InitiatorId: "user001",
    ApproverIds: new[] { "user002", "user003" },
    FormFields: new[] { new ApprovalFormField("采购类型", "IT设备", true) }
));

8. 查询审批状态

var status = await platform.Approval.QueryStatusAsync(instanceId);

9. 通知通道

通过 INotificationDispatcher 发送通知（Channel = "dingtalk"）：

var dispatcher = serviceProvider.GetRequiredService<INotificationDispatcher>();

var result = await dispatcher.SendAsync(new NotificationRequest(
    Channel: "dingtalk",
    Recipient: "cidXXX",                          // 群 OpenConversationId 或用户 userId
    Subject: "订单通知",
    Content: "新订单 #12345 已创建",
    Extra: new Dictionary<string, object?>
    {
        ["TargetType"] = "group",                 // "group" 或 "user"
        ["MsgType"] = "text"                      // "text" 或 "markdown"
    }
));

10. 告警通道

通过 AlarmLogger 自动触发（LogLevel.Warning+），发送到配置的告警群：

var logger = serviceProvider.GetRequiredService<ILogger<MyService>>();
logger.LogWarning("数据库连接超时，已自动重连 {RetryCount}", 3);
// 自动发送告警到 DingTalk.Alarm.OpenConversationId 指定的群

告警内容包含：程序名称、告警名称、告警等级、发生时间、异常详情。

11. 回调处理

在 ASP.NET Core Controller 中接收钉钉回调：

[HttpPost("callback/dingtalk")]
public async Task<IActionResult> DingTalkCallback(
    [FromServices] IImPlatform platform)
{
    using var reader = new StreamReader(Request.Body);
    var rawBody = await reader.ReadToEndAsync();
    var headers = Request.Headers.ToDictionary(h => h.Key, h => h.Value.ToString());
    await platform.Webhook.HandleAsync<object>("dingtalk", rawBody, headers);
    return Ok("success");
}

12. 手机号转 userId

通过 DingTalkClientFactory.GetUserIdByPhoneAsync 将手机号翻译为钉钉 userId，结果缓存 24 小时（未命中缓存 5 分钟防穿透）：

var factory = serviceProvider.GetRequiredService<DingTalkClientFactory>();
var userId = await factory.GetUserIdByPhoneAsync("13800138000");
if (userId != null)
{
    // 发给该 userId
}

自动翻译

Platform 和 NotificationProvider 的消息发送接口会自动检测接收者为 11 位手机号时，自动调用 GetUserIdByPhoneAsync 翻译后发送，无需手动处理：

// TargetId 传手机号即可，自动翻译
await platform.Notification.SendAsync(new ImMessage(
    ImTargetType.User,
    "13800138000",          // 自动翻译为 userId
    ImMessageType.Text,
    "通知", "内容", null));

13. 用户映射

// ERP userId → 钉钉 userId
var dingtalkId = await platform.UserMapping.ToPlatformIdAsync("erp1001", "dingtalk");

// 钉钉 userId → ERP userId
var erpId = await platform.UserMapping.ToErpIdAsync("dingtalk1001", "dingtalk");

配置类

[Options("DingTalk")]
public class DingTalkOptions
{
    public string AppKey { get; set; }
    public string AppSecret { get; set; }
    public string? AgentId { get; set; }
    public string? AesKey { get; set; }
    public string? Token { get; set; }
    public string? RobotCode { get; set; }                // 默认机器人编码
    public AlarmOptions? Alarm { get; set; }              // 告警配置（嵌套类）

    public class AlarmOptions
    {
        public string? RobotCode { get; set; }            // 告警专用机器人编码
        public string? OpenConversationId { get; set; }   // 告警目标群
    }
}

DingTalkClientFactory

DingTalkClientFactory 统一管理钉钉 SDK Client 创建和 access token 缓存，自动注入 DI：

依赖