通知 API

如果您希望以编程方式定义通知通道和源以便进行版本控制和复用，可以使用通知 REST API 来定义、配置和删除通知通道，并发送测试消息。

列出支持的通道配置

要检索所有支持的通知配置类型列表，请向 features 资源发送 GET 请求。

示例请求

GET /_plugins/_notifications/features

示例响应

{
  "allowed_config_type_list" : [
    "slack",
    "chime",
    "webhook",
    "email",
    "sns",
    "ses_account",
    "smtp_account",
    "email_group"
  ],
  "plugin_features" : {
    "tooltip_support" : "true"
  }
}

列出所有通知通道

要检索所有通知通道列表，请向 channels 资源发送 GET 请求。

示例请求

GET /_plugins/_notifications/channels

示例响应

{
  "start_index" : 0,
  "total_hits" : 2,
  "total_hit_relation" : "eq",
  "channel_list" : [
    {
      "config_id" : "sample-id",
      "name" : "Sample Slack Channel",
      "description" : "This is a Slack channel",
      "config_type" : "slack",
      "is_enabled" : true
    },
    {
      "config_id" : "sample-id2",
      "name" : "Test chime channel",
      "description" : "A test chime channel",
      "config_type" : "chime",
      "is_enabled" : true
    }
  ]
}

列出所有通知配置

要检索所有通知配置列表，请向 configs 资源发送 GET 请求。

示例请求

GET _plugins/_notifications/configs

示例响应

{
  "start_index" : 0,
  "total_hits" : 2,
  "total_hit_relation" : "eq",
  "config_list" : [
    {
      "config_id" : "sample-id",
      "last_updated_time_ms" : 1652760532774,
      "created_time_ms" : 1652760532774,
      "config" : {
        "name" : "Sample Slack Channel",
        "description" : "This is a Slack channel",
        "config_type" : "slack",
        "is_enabled" : true,
        "slack" : {
          "url" : "https://sample-slack-webhook"
        }
      }
    },
    {
      "config_id" : "sample-id2",
      "last_updated_time_ms" : 1652760735380,
      "created_time_ms" : 1652760735380,
      "config" : {
        "name" : "Test chime channel",
        "description" : "A test chime channel",
        "config_type" : "chime",
        "is_enabled" : true,
        "chime" : {
          "url" : "https://sample-chime-webhook"
        }
      }
    }
  ]
}

要筛选此请求返回的通知配置类型，您可以使用以下可选路径参数优化查询。

参数	描述
config_id	指定通道标识符。
config_id_list	指定以逗号分隔的通道 ID 列表。
from_index	开始搜索的起始索引。
max_items	请求中返回的最大条目数。
sort_order	指定结果排序方向。有效选项为 asc 和 desc。
sort_field	用于对结果排序的字段。
last_updated_time_ms	通道最后更新的 Unix 时间（毫秒）。
created_time_ms	通道创建的 Unix 时间（毫秒）。
is_enabled	指示通道是否已启用。
config_type	通道类型。有效选项为 sns、slack、chime、webhook、smtp_account、ses_account、email_group 和 email。
name	通道名称。
description	通道描述。
email.email_account_id	通道使用的发件人电子邮件地址。
email.email_group_id_list	通道使用的电子邮件群组。
email.recipient_list	通道收件人列表。
email_group.recipient_list	通道的电子邮件收件人群组列表。
smtp_account.method	电子邮件加密方法。
slack.url	Slack 通道 URL。
chime.url	Amazon Chime 连接 URL。
webhook.url	Webhook URL。
smtp_account.host	SMTP 账户的域名。
smtp_account.from_address	电子邮件账户的发件地址。
smtp_account.method	SMTP 账户的加密方法。
sns.topic_arn	Amazon Simple Notification Service (SNS) 主题的 ARN。
sns.role_arn	Amazon SNS 主题的角色 ARN。
ses_account.region	Amazon Simple Email Service (SES) 账户的 AWS 区域。
ses_account.role_arn	Amazon SES 账户的角色 ARN。
ses_account.from_address	Amazon SES 账户的发件人电子邮件地址。

创建通道配置

要创建通知通道配置，请向 configs 资源发送 POST 请求。

示例请求

POST /_plugins/_notifications/configs/
{
  "config_id": "sample-id",
  "name": "sample-name",
  "config": {
    "name": "Sample Slack Channel",
    "description": "This is a Slack channel",
    "config_type": "slack",
    "is_enabled": true,
    "slack": {
      "url": "https://sample-slack-webhook"
    }
  }
}

创建通道 API 操作在其请求体中接受以下字段：

字段	数据类型	描述	是否必需
config_id	字符串	配置的自定义 ID。	否
config	对象	包含所有相关信息，例如通道名称、配置类型和插件源。	是
name	字符串	通道名称。	是
description	字符串	通道的描述。	否
config_type	字符串	通知的目标地址。有效选项为 sns、slack、chime、webhook、smtp_account、ses_account、email_group 和 email。	是
is_enabled	布尔值	指示通道是否已启用以发送和接收通知。默认为 true。	否

创建通道操作接受多种 config_type 作为可能的通知目标，因此请根据您首选的 config_type 遵循相应的格式。

"sns": {
  "topic_arn": "<arn>",
  "role_arn": "<arn>" //可选
}
"slack": {
  "url": "https://sample-chime-webhoook"
}
"chime": {
  "url": "https://sample-amazon-chime-webhoook"
}
"webhook": {
      "url": "https://custom-webhook-test-url.com:8888/test-path?params1=value1&params2=value2"
}
"smtp_account": {
  "host": "test-host.com",
  "port": 123,
  "method": "start_tls",
  "from_address": "test@email.com"
}
"ses_account": {
  "region": "us-east-1",
  "role_arn": "arn:aws:iam::012345678912:role/NotificationsSESRole",
  "from_address": "test@email.com"
}
"email_group": { //电子邮件收件人群组
  "recipient_list": [
    {
      "recipient": "test-email1@test.com"
    },
    {
      "recipient": "test-email2@test.com"
    }
  ]
}
"email": { //发送电子邮件的通道
  "email_account_id": "<smtp 或 ses 账户配置 id>",
  "recipient_list": [
    {
      "recipient": "custom.email@test.com"
    }
  ],
  "email_group_id_list": []
}

以下示例演示了如何使用电子邮件作为 config_type 创建通道：

POST /_plugins/_notifications/configs/
{
  "id": "sample-email-id",
  "name": "sample-name",
  "config": {
    "name": "Sample Email Channel",
    "description": "Sample email description",
    "config_type": "email",
    "is_enabled": true,
    "email": {
      "email_account_id": "<email_account_id>",
      "recipient_list": [
        "sample@email.com"
      ]
    }
  }
}

示例响应

{
  "config_id" : "<config_id>"
}

获取通道配置

要通过 config_id 获取通道配置，请发送 GET 请求并将 config_id 指定为路径参数。

示例请求

GET _plugins/_notifications/configs/<config_id>

示例响应

{
  "start_index" : 0,
  "total_hits" : 1,
  "total_hit_relation" : "eq",
  "config_list" : [
    {
      "config_id" : "sample-id",
      "last_updated_time_ms" : 1652760532774,
      "created_time_ms" : 1652760532774,
      "config" : {
        "name" : "Sample Slack Channel",
        "description" : "This is a Slack channel",
        "config_type" : "slack",
        "is_enabled" : true,
        "slack" : {
          "url" : "https://sample-slack-webhook"
        }
      }
    }
  ]
}

更新通道配置

要更新通道配置，请向 configs 资源发送 POST 请求，并将通道的 config_id 指定为路径参数。在请求体中指定新的配置详情。

示例请求

PUT _plugins/_notifications/configs/<config_id>
{
  "config": {
    "name": "Slack Channel",
    "description": "This is an updated channel configuration",
    "config_type": "slack",
    "is_enabled": true,
    "slack": {
      "url": "https://hooks.slack.com/sample-url"
    }
  }
}

示例响应

{
  "config_id" : "<config_id>"
}

删除通道配置

要删除通道配置，请向 configs 资源发送 DELETE 请求，并将 config_id 指定为路径参数。

示例请求

DELETE /_plugins/_notifications/configs/<config_id>

示例响应

{
  "delete_response_list" : {
  "<config_id>" : "OK"
  }
}

您还可以提交一个以逗号分隔的、要删除的通道 ID 列表，UDB-SX 将删除所有指定的通知通道。

示例请求

DELETE /_plugins/_notifications/configs/?config_id_list=<config_id1>,<config_id2>,<config_id3>...

示例响应

{
  "delete_response_list" : {
  "<config_id1>" : "OK",
  "<config_id2>" : "OK",
  "<config_id3>" : "OK"
  }
}

发送测试通知

要发送测试通知，请向 /feature/test/ 发送 GET 请求，并将通道配置的 config_id 指定为路径参数。

示例请求

GET _plugins/_notifications/feature/test/<config_id>

示例响应

{
  "event_source" : {
    "title" : "Test Message Title-0Jnlh4ABa4TCWn5C5H2G",
    "reference_id" : "0Jnlh4ABa4TCWn5C5H2G",
    "severity" : "info",
    "tags" : [ ]
  },
  "status_list" : [
    {
      "config_id" : "0Jnlh4ABa4TCWn5C5H2G",
      "config_type" : "slack",
      "config_name" : "sample-id",
      "email_recipient_status" : [ ],
      "delivery_status" : {
        "status_code" : "200",
        "status_text" : """<!doctype html>
<html>
<head>
</head>
<body>
<div>
    <h1>Example Domain</h1>
    <p>Sample paragraph.</p>
    <p><a href="sample.example.com">TO BE OR NOT TO BE, THAT IS THE QUESTION</a></p>
</div>
</body>
</html>
"""
      }
    }
  ]
}