← 文章 / 云原生与基础设施

signoz 4小时前 · 2026-09-25 23:10:14 · 0 阅读

将通知渠道 API 从 v1 端点迁移至 v2 端点

v1 通知渠道 API 端点已弃用，并将在即将发布的版本中移除。v2 端点取代了这些旧端点，引入了强制的请求结构并修复了安全漏洞。一旦 v1 端点被移除，针对它们的请求将失败。

在 /api/v2/notification_channels 路径下提供了对应的替代端点。包括所有端点的请求和响应结构在内的完整 v2 规范，可在 SigNoz API 参考中查阅。

v2 端点自 SigNoz v0.141.0 起处于开发阶段。弃用 v1 端点的版本同时也标志着 v2 端点结束开发。v2 路由在以下版本中逐步落地：

版本	新增的 v2 渠道路由
`v0.141.0`	仅支持 `POST` 创建
`v0.142.0`	列表、获取、更新、删除、测试
`v0.143.0`	`POST /{id}/repair`

端点映射

v1 (已移除)	v2 (替代)
`GET /api/v1/channels`	`GET /api/v2/notification_channels`
`GET /api/v1/channels/{id}`	`GET /api/v2/notification_channels/{id}`
`POST /api/v1/channels`	`POST /api/v2/notification_channels`
`PUT /api/v1/channels/{id}`	`PUT /api/v2/notification_channels/{id}`
`DELETE /api/v1/channels/{id}`	`DELETE /api/v2/notification_channels/{id}`
`POST /api/v1/channels/test`	`POST /api/v2/notification_channels/test`
`POST /api/v1/testChannel`	`POST /api/v2/notification_channels/test`
—	`POST /api/v2/notification_channels/{id}/repair` (新增)

渠道 ID 保持不变。在 v1 中有效的 ID 在 v2 中同样有效。

授权

认证方式不变：原有的 API 密钥或会话继续有效。授权机制从 v1 的固定角色门禁转变为通过 OpenFGA 进行按资源检查。托管角色保留其 v1 访问权限。在企业版中，可以单独为自定义角色授予以下权限。

v2 endpoint	权限	可管理的角色
`POST /api/v2/notification_channels`	`notification-channel:create`	admin
`GET /api/v2/notification_channels`	`notification-channel:list`	admin、editor、viewer
`GET /api/v2/notification_channels/{id}`	`notification-channel:read`	admin、editor、viewer
`PUT /api/v2/notification_channels/{id}`	`notification-channel:update`	admin
`DELETE /api/v2/notification_channels/{id}`	`notification-channel:delete`	admin
`POST /api/v2/notification_channels/{id}/repair`	`notification-channel:update`	admin
`POST /api/v2/notification_channels/test`	`notification-channel:create`	admin、editor

新的请求 schema

v2 对每个请求都强制执行 schema 校验。通道在 config.kind 中声明类型，该类型的所有配置项都以 camelCase 形式放在 config.spec 里。任何层级出现未知字段都会被拒绝。

完整 schema 见 API 参考文档中 Create Notification Channel endpoint 的请求体。从整体上看，每个通道的结构如下：

Copy

{
  "name": "string",
  "displayName": "string",
  "generateName": false,
  "config": {
    "kind": "slack | email | webhook | pagerduty | opsgenie | msteams | googlechat | jira | jsmops | incidentio",
    "spec": { /* 对应类型的配置 */ }
  }
}

每个通道有两个名称：name 是不可变的标识符，格式为 DNS-1123 label；displayName 是界面上显示的自由文本标签，告警规则和路由策略通过它来引用通道。v1 的 name 对应 v2 的 displayName，v2 的 name 是新增的。将 generateName 设为 true 可根据 displayName 加随机后缀自动生成 name；若省略 displayName，则默认等于 name。

更新和测试请求只需携带 config。

创建通知通道

创建请求是上述请求体的 POST 调用。例如，创建 Slack 频道：

Copy

curl -X POST "https://<your-signoz-host>/api/v2/notification_channels" \
  -H "SIGNOZ-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "oncall-slack",
    "displayName": "On-call Slack",
    "config": {
      "kind": "slack",
      "spec": {
        "apiUrl": "https://hooks.slack.com/services/T000/B000/XXXX",
        "channel": "#alerts",
        "sendResolved": true
      }
    }
  }'

请核实以下值：

<your-signoz-host>：您的 SigNoz 实例主机，例如 example.signoz.io。
<your-api-key>：拥有授权章节中所述权限的服务账号 API key。创建频道需要 Admin 角色。关于如何创建，请参阅服务账号文档。

创建成功返回 201，包含已存储的频道及其 id。如果请求体中任何层级的字段未在 schema 中定义，将被以 400 拒绝，不会静默丢弃。

各类型的 config 配置

v1 将配置包裹在 <kind>_configs 数组中，并通过该键名标识类型。v2 将它们包裹在 config 中，在 kind 字段中指定类型，并使用 camelCase 书写配置。例如，Slack 使用以下结构替代 slack_configs：

Copy

// v1
{
  "name": "On-call Slack",
  "slack_configs": [
    {
      "api_url": "https://hooks.slack.com/services/T000/B000/XXXX",
      "channel": "#alerts",
      "send_resolved": true
    }
  ]
}

Copy

// v2
{
  "name": "oncall-slack",
  "displayName": "On-call Slack",
  "config": {
    "kind": "slack",
    "spec": {
      "apiUrl": "https://hooks.slack.com/services/T000/B000/XXXX",
      "channel": "#alerts",
      "sendResolved": true
    }
  }
}

其他所有支持类型均遵循相同模式：

v2 `kind`	替代
`slack`	`slack_configs`
`email`	`email_configs`
`webhook`	`webhook_configs`
`pagerduty`	`pagerduty_configs`
`opsgenie`	`opsgenie_configs`
`msteams`	`msteamsv2_configs`
`googlechat`	`googlechat_configs`
`jira`	`jira_configs`
`jsmops`	`jsmops_configs`
`incidentio`	`incidentio_configs`

除了大小写变更，还有两类配置涉及字段移动。Webhook 认证不再使用 http_config 字段：

Copy

// v1
"webhook_configs": [
  {
    "url": "https://hooks.example.com/signoz",
    "http_config": {
      "basic_auth": { "username": "signoz", "password": "s3cret" }
    }
  }
]

Copy

// v2
"config": {
  "kind": "webhook",
  "spec": {
    "url": "https://hooks.example.com/signoz",
    "username": "signoz",
    "password": "s3cret"
  }
}

类型 Bearer 的 http_config.authorization 也会变成 bearerToken。Jira 凭据同样不再保留在 http_config 中：

Copy

// v1
"jira_configs": [
  {
    "site": "https://acme.atlassian.net",
    "project": "OPS",
    "issue_type": "Incident",
    "http_config": {
      "basic_auth": { "username": "oncall@example.com", "password": "ATATT3xFfGF0..." }
    }
  }
]

Copy

// v2
"config": {
  "kind": "jira",
  "spec": {
    "site": "https://acme.atlassian.net",
    "project": "OPS",
    "issueType": "Incident",
    "email": "oncall@example.com",
    "apiToken": "ATATT3xFfGF0..."
  }
}

各类型完整的字段列表请参考 SigNoz API 参考文档。

更新通知渠道

更新操作是对渠道 id 发起 PUT 请求，请求体仅包含 config。config 会被整体替换：更新中未包含的字段将被移除，而非保留原有值。

Copy

curl -X PUT "https://<your-signoz-host>/api/v2/notification_channels/<channel-id>" \
  -H "SIGNOZ-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "kind": "slack",
      "spec": {
        "apiUrl": "https://hooks.slack.com/services/T000/B000/XXXX",
        "channel": "#alerts-prod",
        "sendResolved": true
      }
    }
  }'

请核对以下取值：

<channel-id>：频道的 id，由创建和列表接口返回。

name 不可修改。displayName 目前也无法修改，因为告警规则和路由策略仍通过它来引用频道，后续版本会支持更新。

列出通知频道

列表接口支持分页、过滤和排序，且只返回元数据：id、name、displayName、kind、createdAt、updatedAt，以及 total 总数。如需查看某个频道的 config，请通过 id 单独获取。

参数	含义
`query`	对 `displayName` 做不区分大小写的匹配。
`kind`	只返回该类型的频道。
`sort`	`updated_at`（默认）、`created_at` 或 `name`（即按 `displayName` 排序）。
`order`	`desc`（默认）或 `asc`。
`limit`	每页数量，默认 20，最大 200。
`offset`	跳过的频道数量。

例如，获取所有 Slack 频道：

Copy

curl "https://<your-signoz-host>/api/v2/notification_channels?kind=slack" \
  -H "SIGNOZ-API-KEY: <your-api-key>"

获取显示名包含 "on-call" 的频道，并按字母顺序排列：

Copy

curl "https://<your-signoz-host>/api/v2/notification_channels?query=on-call&sort=name&order=asc" \
  -H "SIGNOZ-API-KEY: <your-api-key>"

获取每页 50 条的第 2 页：

Copy

curl "https://<your-signoz-host>/api/v2/notification_channels?limit=50&offset=50" \
  -H "

 原始来源： signoz 
    
  评论 (0)