JSM Alert

通过 Jira Service Management（原 Opsgenie）Alert REST API，把告警推送到 JSM 做排班、升级与复盘。

概述

Jira Service Management Alerts（简称 JSM，原 Atlassian Opsgenie 产品，现已合并到 JSM 旗下）是 Atlassian 提供的告警响应 / On-Call 管理平台。通过 Alert REST API 把告警推送过去后，JSM 会负责：

按团队排班与轮值；
多级升级（Escalation）、电话 / 短信 / App 推送；
告警去重、关联工单、SLA 统计。

夜莺的 JSM 集成使用 JSM Alerts API 的两个端点：

触发：POST /v2/alerts 创建告警；
恢复：POST /v2/alerts/{alias}/close?identifierType=alias 关闭告警。

二者通过告警的 alias（取 {{$event.Hash}}，也就是夜莺事件的 RuleID + 维度哈希）匹配——同一个 alias 触发后再发 close 就会关闭。

适用场景：海外团队使用 Atlassian 全家桶，或希望把监控告警打通到 JSM 工单系统。
你需要准备：
- 一个 Atlassian Cloud / JSM 实例；
- 在 JSM Operations → Integrations 里创建一个 API integration 或 Nightingale 类型集成，拿到 API Key；
整个配置分三步：①在 JSM 创建 API 集成拿到 API Key → ②在夜莺新建 JSM Alert 通知媒介 → ③在通知规则里填入 API Key。

第一步：在 JSM 创建集成拿到 API Key

登录你的 Atlassian 实例，进入 Jira Service Management → Operations（或直接访问 https://<your-team>.app.opsgenie.com/settings/integration/integration-list）。
左侧 Settings → Integrations → Add integration。
在列表里搜索并选择 API（通用 REST API 集成；如果看到名为"Nightingale"的专用集成也可以选，效果等价）。
填写名称（例如 Nightingale），选择处理此集成告警的团队（Responders）。
保存后页面上会显示一段 API Key，形如：
```
1234abcd-5678-90ef-1234-567890abcdef
```
保存好，这就是后面夜莺里要填的 api_key。

JSM 的告警 API 对不同 Atlassian 区域有不同域名：

全球 / 北美：https://api.atlassian.com/jsm/ops/integration/v2/alerts（夜莺默认 URL）；

欧盟：https://api.eu.atlassian.com/...；

如果你的 JSM 是独立 Opsgenie（未迁移到 JSM 统一鉴权）：https://api.opsgenie.com/v2/alerts 或 https://api.eu.opsgenie.com/v2/alerts。

默认的夜莺 URL 是 JSM 统一端点；如果你用旧的 Opsgenie 域名，请在媒介表单里把 URL 改过来。

第二步：在夜莺新建 JSM Alert 通知媒介

登录夜莺 → 左侧菜单 通知 → 通知媒介。
在左侧类型面板点击 JSM Alert（URL /notification-channels/add?ident=jsm_alert）。

填写表单，系统已预置好所有模板，只需改名称：

JSM Alert 基础配置

区块	字段	说明
基础配置	名称	例如 `JSM Alert`
变量配置	参数配置	保持默认，已预置 `api_key` 一个参数
HTTP 配置	URL	默认 `https://api.atlassian.com/jsm/ops/integration/v2/alerts...`，里面带 `{{if $event.IsRecovered}}/{{$event.Hash}}/close?identifierType=alias{{end}}`——触发时拼成创建，恢复时拼成关闭
HTTP 配置	请求方法	`POST`
HTTP 配置	请求头 `Authorization`	`GenieKey {{$params.api_key}}`（保持默认；`GenieKey` 是 JSM 对 API Key 的鉴权前缀）
HTTP 配置	请求头 `Content-Type`	`application/json`

再往下看到"请求体"，也是保持默认：

默认请求体用 Go template 根据 IsRecovered 分两段：
```
{{if $event.IsRecovered}}
  {"note":"{{$tpl.content}}","source":"{{$event.Cluster}}"}
{{else}}
  {
    "message":"{{$event.RuleName}}",
    "description":"{{$tpl.content}}",
    "alias":"{{$event.Hash}}",
    "priority":"P{{$event.Severity}}",
    "tags":[ ...标签列表... ],
    "details":{{jsonMarshal $event.AnnotationsJSON}},
    "entity":"{{$event.TargetIdent}}",
    "source":"{{$event.Cluster}}"
  }
{{end}}
```
字段含义：
- message → JSM 告警标题，用夜莺的告警规则名；
- description → 告警详情，用你选的消息模板（推荐 Markdown 或纯文本）渲染的内容；
- alias → 告警别名，夜莺事件的 Hash，相同 alias 的后续事件会被 JSM 视为同一告警；
- priority → P1~P5，直接用夜莺的 Severity（1~3）拼成；若想把告警级别映射成 P1/P2/P3，可在消息模板里做 switch；
- tags / entity / source → 方便 JSM 侧的过滤与路由。
点击保存。

第三步：在通知规则里填入 API Key

左侧菜单 通知 → 通知规则 → 新增（或编辑已有规则）。
在"通知配置"区域：
- 通知媒介：选刚才创建的 JSM Alert 媒介；
- 消息模板：选一个能产生 Markdown 或纯文本的模板（description 最长 15,000 字符）；
- API Key：粘贴第一步拿到的 api_key；
- 适用级别 / 适用时段 / 适用标签：按需过滤。
保存后点击"通知测试"——JSM 里应该立刻能看到一条测试告警，等告警恢复后会被自动 close。

常见问题

Q1：返回 401 Unauthorized / AuthenticationException？

api_key 填错；
你用的是 Opsgenie legacy API Key，但 URL 指向了 JSM 新端点（或反之）——对齐一下；
该 API 集成在 JSM 后台被关闭，重新打开 “Enabled” 开关。

Q2：返回 404 Not Found / alias 关闭失败？

A：JSM 关闭接口要求告警存在。常见原因：

告警刚触发还没来得及落库，立刻又恢复；
alias 的长度超过 512 字节（夜莺 Hash 一般是 64 字符以内，不会超限）；
API Key 所在集成没有这个告警的操作权限。

Q3：告警重复触发为什么没有去重？

A：JSM 默认按 alias 去重——同 alias 再次调用 /v2/alerts，返回 202 且不会新建。如果你看到重复告警：

检查告警规则的 Hash 是否稳定（夜莺 Hash 由规则 ID + 维度标签组成，改规则 ID 或标签都会产生新 hash）；
检查 JSM 集成是否开启了 “Alert de-duplication”。

Q4：告警内 priority 与 JSM 的 P1~P5 不一致？

A：默认模板直接把夜莺的 Severity（1/2/3）拼成 P1/P2/P3。如果 JSM 里的响应策略（Heartbeat / Policy）是按 P4/P5 分级的，需要在消息模板里做映射：

{{- $pri := "P3" -}}
{{- if eq $event.Severity 1 -}}{{- $pri = "P1" -}}{{- end -}}
{{- if eq $event.Severity 2 -}}{{- $pri = "P2" -}}{{- end -}}
...

Q5：如何把 JSM 的认领/关闭事件反向同步回夜莺？

A：需要在 JSM 里额外配置 Webhook 回调到夜莺的 OpenAPI（告警认领 / 屏蔽接口），超出本文范围，参考夜莺开放 API 文档。

Q6：EU 实例该填什么 URL？

A：把默认 URL 里的 api.atlassian.com 换成 api.eu.atlassian.com。如果是独立 Opsgenie（已经少见），换成 api.opsgenie.com 或 api.eu.opsgenie.com，鉴权头依然是 GenieKey <api-key>。

概述

第一步：在 JSM 创建集成拿到 API Key

第二步：在夜莺新建 JSM Alert 通知媒介

第三步：在通知规则里填入 API Key

常见问题

参考资料