跳至主要內容

消息推送系统 API 文档

大约 3 分钟

消息推送系统 API 文档

概述

本文档基于 message_push.proto，描述消息推送系统的 gRPC 接口，覆盖邮件配置、钉钉配置与消息发送能力。

包信息

  • 包名: message_push
  • 语法版本: proto3

通用枚举与消息

Encryption（加密方式）

枚举值说明
NONE = 0不加密
SSL = 1SSL 加密
TLS = 2TLS 加密

email_config（邮箱配置）

字段类型说明
email_config_idint64邮箱配置 ID
send_emailstring发送者邮箱
send_user_namestring发送者用户名
smtp_hoststringSMTP 服务器
smtp_portint32SMTP 端口
smtp_passwordstringSMTP 密码
smtp_user_namestringSMTP 用户名
encryptionEncryption加密方式

ding_ding_config（钉钉配置）

字段类型说明
ding_ding_config_idint64钉钉配置 ID
webhook_urlstring钉钉 webhook
secretstring钉钉签名密钥

服务接口

服务名：MessagePushService

1. 邮箱配置

1.1 新增邮箱配置 CreatePushEmailConfig

请求参数：

message PushEmailConfigRequest {
  string access_token = 8;
  string send_email = 1;
  string send_user_name = 2;
  string smtp_host = 3;
  int32 smtp_port = 4;
  string smtp_password = 5;
  string smtp_user_name = 6;
  Encryption encryption = 7;
}

响应参数：

message PushEmailConfigResponse {
  string message = 1;
  int32 code = 2;
}

RPC：

rpc CreatePushEmailConfig(PushEmailConfigRequest) returns (PushEmailConfigResponse);

1.2 获取邮箱配置列表 GetPushEmailConfigList

请求：GetPushEmailConfigListRequest { string access_token = 1; }

响应：GetPushEmailConfigListResponse { string message = 1; int32 code = 2; }

RPC：

rpc GetPushEmailConfigList(GetPushEmailConfigListRequest) returns (GetPushEmailConfigListResponse);

1.3 删除邮箱配置 DeletePushEmailConfig

请求：DeletePushEmailConfigRequest { string access_token = 1; int64 email_config_id = 2; }

响应：DeletePushEmailConfigResponse { string message = 1; int32 code = 2; }

RPC：

rpc DeletePushEmailConfig(DeletePushEmailConfigRequest) returns (DeletePushEmailConfigResponse);

1.4 更新邮箱配置 UpdatePushEmailConfig

请求：

message UpdatePushEmailConfigRequest {
  string access_token = 1;
  int64 email_config_id = 2;
  string send_email = 3;
  string send_user_name = 4;
  string smtp_host = 5;
  int32 smtp_port = 6;
  string smtp_password = 7;
  string smtp_user_name = 8;
}

响应：UpdatePushEmailConfigResponse { string message = 1; int32 code = 2; }

RPC：

rpc UpdatePushEmailConfig(UpdatePushEmailConfigRequest) returns (UpdatePushEmailConfigResponse);

1.5 获取邮箱配置详情 GetPushEmailConfig

请求：GetPushEmailConfigRequest { string access_token = 1; int64 email_config_id = 2; }

响应：

message GetPushEmailConfigResponse {
  string message = 1;
  int32 code = 2;
  email_config email_config = 3;
}

RPC：

rpc GetPushEmailConfig(GetPushEmailConfigRequest) returns (GetPushEmailConfigResponse);

1.6 发送邮件 SendEmail

请求：

message SendEmailRequest {
  string access_token = 1;
  string email = 2;
  int64 email_config_id = 3;
  string title = 4;
  string content = 5;
}

响应：SendEmailResponse { string message = 1; int32 code = 2; }

RPC：

rpc SendEmail(SendEmailRequest) returns (SendEmailResponse);

2. 钉钉配置

2.1 新增钉钉配置 CreatePushDingDingConfig

请求：PushDingDingConfigRequest { string access_token = 1; string webhook_url = 2; string secret = 3; }

响应：PushDingDingConfigResponse { string message = 1; int32 code = 2; }

RPC：

rpc CreatePushDingDingConfig(PushDingDingConfigRequest) returns (PushDingDingConfigResponse);

2.2 获取钉钉配置列表 GetPushDingDingConfigList

请求：GetPushDingDingConfigListRequest { string access_token = 1; int64 ding_ding_config_id = 2; }

响应：

message GetPushDingDingConfigListResponse {
  string message = 1;
  int32 code = 2;
  repeated ding_ding_config ding_ding_config = 3;
}

RPC：

rpc GetPushDingDingConfigList(GetPushDingDingConfigListRequest) returns (GetPushDingDingConfigListResponse);

2.3 删除钉钉配置 DeletePushDingDingConfig

请求：DeletePushDingDingConfigRequest { string access_token = 1; int64 ding_ding_config_id = 2; }

响应：DeletePushDingDingConfigResponse { string message = 1; int32 code = 2; }

RPC：

rpc DeletePushDingDingConfig(DeletePushDingDingConfigRequest) returns (DeletePushDingDingConfigResponse);

2.4 更新钉钉配置 UpdatePushDingDingConfig

请求：

message UpdatePushDingDingConfigRequest {
  string access_token = 1;
  int64 ding_ding_config_id = 2;
  string webhook_url = 3;
  string secret = 4;
}

响应：UpdatePushDingDingConfigResponse { string message = 1; int32 code = 2; }

RPC：

rpc UpdatePushDingDingConfig(UpdatePushDingDingConfigRequest) returns (UpdatePushDingDingConfigResponse);

2.5 获取钉钉配置详情 GetPushDingDingConfig

请求：GetPushDingDingConfigRequest { string access_token = 1; int64 ding_ding_config_id = 2; }

响应：

message GetPushDingDingConfigResponse {
  string message = 1;
  int32 code = 2;
  ding_ding_config ding_ding_config = 3;
}

RPC：

rpc GetPushDingDingConfig(GetPushDingDingConfigRequest) returns (GetPushDingDingConfigResponse);

2.6 发送钉钉消息 sendDingDing

请求：

message SendingDingDingRequest {
  string access_token = 1;
  int64 ding_ding_config_id = 2;
  string mobile = 3;
  string title = 4;
  string content = 5;
}

响应：SendingDingDingResponse { string message = 1; int32 code = 2; }

RPC：

rpc sendDingDing(SendingDingDingRequest) returns (SendingDingDingResponse);

状态码说明

code说明
200成功
400参数错误
401未授权
403权限不足
404资源不存在
500服务器内部错误

使用示例（Go）

以下示例仅演示调用方式，需替换实际 pb 包路径和服务地址。

发送邮件示例

conn, _ := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
cli := pb.NewMessagePushServiceClient(conn)

_, _ = cli.CreatePushEmailConfig(context.Background(), &pb.PushEmailConfigRequest{
  AccessToken:   "token",
  SendEmail:     "noreply@example.com",
  SendUserName:  "Ops",
  SmtpHost:      "smtp.example.com",
  SmtpPort:      465,
  SmtpPassword:  "pwd",
  SmtpUserName:  "noreply@example.com",
  Encryption:    pb.Encryption_SSL,
})

resp, _ := cli.SendEmail(context.Background(), &pb.SendEmailRequest{
  AccessToken:   "token",
  Email:         "user@example.com",
  EmailConfigId: 1,
  Title:         "告警通知",
  Content:       "CPU 使用率过高",
})
fmt.Println(resp.Code, resp.Message)

发送钉钉消息示例

conn, _ := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
cli := pb.NewMessagePushServiceClient(conn)

_, _ = cli.CreatePushDingDingConfig(context.Background(), &pb.PushDingDingConfigRequest{
  AccessToken: "token",
  WebhookUrl:  "https://oapi.dingtalk.com/robot/send?access_token=...",
  Secret:      "xxx",
})

resp, _ := cli.SendDingDing(context.Background(), &pb.SendingDingDingRequest{
  AccessToken:       "token",
  DingDingConfigId:  1,
  Mobile:            "13800138000",
  Title:             "系统通知",
  Content:           "任务已完成",
})
fmt.Println(resp.Code, resp.Message)

代码生成（Go）

protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       message_push.proto

注意事项

  1. 邮件配置中的敏感字段（如 smtp_password）需安全存储。
  2. 钉钉 secret 与 webhook_url 建议通过密钥管理系统注入。
  3. 发送频率可在服务端做限流防止滥用。
  4. code 字段请结合服务端文档获取更完整的错误语义。
许昌智能