- 快猫星云Flashcat

透過 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}}`——觸發時會拼成建立 URL，恢復時會拼成關閉 URL
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

常見問題

參考資料