我用 Amazon Q Developer 把 SNS 警報送進 Slack — 只發布一則 SNS 訊息,依訂閱協定送出不同的內容
Amazon Q Developer 會丟棄純文字的 SNS 訊息。發布時加上 MessageStructure=json,同一則訊息就能讓電子郵件收到純文字、讓 Slack 收到自訂通知。

本頁目錄
引言
我在 AWS 上運行一個文件翻譯工作流,目前每一則警報是以 SNS 電子郵件寄來,但我打算同時讓它將錯誤警報也送到團隊的 Slack 頻道上。 Amazon Q Developer in chat applications(前身為 AWS Chatbot)不必寫程式就能把 SNS 主題接到 Slack 上。所以在導入 production 環境之前,我先在自己的工作區試了一次。
CloudWatch 警示順利送到了 Slack,但我自己的程式發布的訊息全都被默默丟棄了。這是因為 Amazon Q Developer 只接受它自訂的通知 JSON。
解決方法是發布時加上 MessageStructure=json,只發布一則 SNS 訊息,就能讓電子郵件收到純文字的內容,讓 Slack 收到自訂通知的 JSON。
每個警報來源依然只呼叫一次 Publish,CloudWatch 警示送到 Slack 的方式也完全不受影響。
警報如何送到 Slack?
Amazon Q Developer in chat applications 以頻道組態(channel configuration)為單位設定。一個頻道組態包含三樣東西:
- Slack 頻道:接收警報的頻道,一個頻道組態只對應一個頻道。
- SNS 主題:負責把通知送進這個頻道的主題,可以指定多個。
- IAM role:在頻道裡輸入的指令會以這個 role 的身分執行。
建立頻道組態後,Amazon Q Developer 會以 HTTPS 訂閱每一個主題。主題原本的電子郵件訂閱則維持不變。
有兩個步驟仍然需要手動完成:
- 核准 AWS 應用程式:要由能存取該 Slack 工作區的人在 OAuth 畫面上核准。這個畫面要從 Amazon Q Developer 主控台開啟,而這個主控台只能在美國東部(俄亥俄)使用。
- 邀請到私人頻道:如果是私人頻道,還要在該頻道輸入
/invite @Amazon Q,否則私人頻道什麼都收不到。
其餘的部分全都可以用 CDK 完成。
aws-cdk-lib/aws-chatbot 的 SlackChannelConfiguration 有一個可省略的 role 屬性。下面的程式碼沒有指定 role,所以 CDK 會自動建立一個只有 trust policy、沒有任何權限的 role。我另外把 ReadOnlyAccess 設為 guardrail。guardrail 是一種 IAM 政策,不論 role 有什麼權限,頻道裡的指令最多只能做到 guardrail 允許的範圍。
這個頻道只負責接收警報。即使在頻道裡對 @Amazon Q 輸入指令,也無法變更帳戶裡的任何東西。
new chatbot.SlackChannelConfiguration(this, 'SlackAlerts', { slackChannelConfigurationName: 'dev-alerts', slackWorkspaceId: 'T0123456789', slackChannelId: 'C0123456789', notificationTopics: [notificationTopic, opsAlertTopic], guardrailPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName('ReadOnlyAccess')], loggingLevel: chatbot.LoggingLevel.ERROR,});這個 stack 位於東京區域。雖然 Amazon Q Developer 主控台只能在俄亥俄使用,頻道組態還是可以直接從東京的 stack 部署,不需要另外建立美國區域的 stack。
為什麼純文字的 SNS 訊息送不到 Slack?
Amazon Q Developer 會丟棄純文字的 SNS 訊息,而且只會留下一行日誌:
Event received is not supported (see https://docs.aws.amazon.com/chatbot/latest/adminguide/related-services.html ): {"type":"Notification", … "message":"TEST1b: …", …}Amazon Q Developer 會自行排版它支援的 AWS 服務通知,例如 CloudWatch 警示。其他訊息則必須使用自訂通知格式。
自訂通知是一個 JSON 物件,version 設為 "1.0"、source 設為 "custom",並且要有 content.description:
{ "version": "1.0", "source": "custom", "content": { "textType": "client-markdown", "title": ":x: [prod] Translation failed", "description": "*File ID*: `123456`" }}每則自訂通知都會帶著固定的頁尾「Custom notification delivered by Amazon Q Developer」,而這個格式沒有任何欄位能移除它。
一則 SNS 訊息,依訂閱協定送出不同的內容
MessageStructure=json 能讓一次 Publish 呼叫為每一種訂閱協定送出不同的內容。
這時 Message 會變成一個 JSON 物件,key 是協定名稱,值是字串。
default 是必填的,會用於所有沒有專屬 key 的協定。https 則用於 HTTPS 訂閱者,而 Amazon Q Developer 正是以 HTTPS 訂閱的。
def publish_notice(client, *, topic_arn: str, notice: Notice) -> None: message = { "default": email_text(notice), "https": json.dumps(slack_notice(notice), ensure_ascii=False), } client.publish( TopicArn=topic_arn, Subject=subject_safe(notice.subject)[:99], Message=json.dumps(message, ensure_ascii=False), MessageStructure="json", )https 的值是包在 JSON 字串裡的 JSON,所以會被編碼兩次。
電子郵件和以前一樣,收到 default 的內容和 Subject。
https key 的內容會送到每一個 HTTPS 訂閱者,並不只是 Amazon Q Developer。
目前唯一的 HTTPS 訂閱者是 Amazon Q Developer。
如果之後有 Webhook 訂閱了同一個主題,這個 Webhook 也會收到自訂通知的 JSON,所以我在 https key 旁邊留了一行註解提醒這件事。
同一個 Notice,分別產生電子郵件與 Slack 的版本
工作流裡會發布警報的地方,主要分成兩類:
- 單次嘗試失敗:翻譯之類的工作執行失敗,但之後還會重試。
- 重試次數用盡:工作用完了重試次數、進入 dead-letter queue,由通知程式發出警報。
我讓這些地方都先建立一個 Notice,再交給 publish_notice(),由它把同一個 Notice 產生成電子郵件和 Slack 兩個版本。
@dataclass(frozen=True)class Notice: title: str # 部署名稱 label: str # "Translation failed" lead: str severity: Severity = "warning" target: str = "" # 只用於電子郵件主旨 fields: tuple = () # 電子郵件與 Slack email_fields: tuple = () # 只用於電子郵件 notes: str = "" blocks: tuple = () # 電子郵件與 Slack email_blocks: tuple = () # 只用於電子郵件 next_steps: tuple = () thread_id: str = ""不讓檔名出現在 Slack
檔名以及從檔案裡取出的任何內容,都只放在電子郵件裡。 這個專案規定檔名和檔案內容不能送到 Slack。
Notice 有三個只給電子郵件用的欄位:
target:只出現在電子郵件主旨裡的文字,例如檔名。email_fields:只出現在電子郵件內文裡的「名稱:值」,例如「檔案:report_v2.docx」。email_blocks:只出現在電子郵件內文裡的整段文字,例如試算表的欄位標題或原始的佇列訊息。
slack_notice() 不讀這三個欄位,所以這些資訊不會出現在 Slack。如果有資訊因此被省略,Slack 訊息最後會加上一行,說明細節請見電子郵件。
next_steps 對應到自訂格式的 nextSteps,Slack 會把它顯示成「Next steps:」標籤下的項目清單。
severity 決定 Slack 標題裡的表情符號。單次嘗試失敗時顯示 ❌,用完重試次數的翻譯工作則顯示 🚨。
用 threadId 把同一個檔案當天的失敗歸進同一個討論串
thread_id 對應到 metadata.threadId。當訊息帶著 Amazon Q Developer 先前收過的 ID 時,Amazon Q Developer 會把這則訊息張貼成討論串裡的回覆。
我用翻譯工作的 key 作為 ID(例如 box#123456,由來源服務和檔案 ID 組成),所以同一個檔案每次嘗試的失敗和當次的 dead-letter 通知,都會集中在同一個討論串裡。
Amazon Q Developer 預設會把 2 天內 ID 相同的訊息歸進同一個討論串。所以我讓 slack_notice() 在 Slack 討論串 ID 後面加上日本時間的日期。這樣一來,如果同樣的失敗隔天又發生,就會開啟一個新的討論串:
payload["metadata"] = { "threadId": f"{notice.thread_id}#{_today()}", # box#123456#2026-11-05 "summary": _slack_escape(notice.heading),}回覆送達時,Amazon Q Developer 會把 summary 以 Latest Update 的形式加在討論串第一則訊息上,這樣不必打開討論串,也能在頻道上看到最新狀態。
![Amazon Q Developer 張貼的 Slack 討論串。第一則訊息的標題是紅色叉號加上「[prod] Translation failed」,下面依序是寫著「[prod] Translation failed (retries used up)」的 Latest Update 一行、以行內程式碼呈現的服務、檔案 ID 與工作 ID、以程式碼區塊呈現的原因,以及一個 Next steps 項目。唯一的一則回覆以警笛和「[prod] Translation failed (retries used up)」為標題,列出同一個檔案 ID、觸發事件、時間,以及它自己的下一步。第一則訊息以「Custom notification delivered by Amazon Q Developer」頁尾結束。兩則訊息都沒有出現檔名。](/_astro/slack-thread@2x.DwcBxE3y_ZIGFq.webp)
對應 Slack 特有的 mrkdwn 語法
textType: "client-markdown" 告訴 Amazon Q Developer,title 和 description 裡的文字是 Slack 的 mrkdwn。mrkdwn 是 Slack 自己的標記語法,例如 *粗體* 和 _斜體_。
直接用 Slack 的 API 發訊息時,可以用 plain_text 文字物件或 mrkdwn: false 關閉格式。但 Amazon Q Developer 的自訂通知格式沒有對應的欄位,所以無法關閉。
*v2* 經過 Amazon Q Developer 送到 Slack 後,星號不見了,v2 變成粗體。每個值都用反引號包起來,讓 Slack 顯示成行內程式碼或程式碼區塊,因為 mrkdwn 在這兩種格式裡不會生效。
fields 會顯示成行內程式碼,blocks 則顯示成程式碼區塊。
但即使包在反引號裡,&、< 和 > 還是要跳脫,因為 Slack 用這三個字元來標記連結和提及(例如 <@U123>),即使在程式碼或程式碼區塊裡也不例外。因此我寫了兩個函式來處理這些情況:
def _inline_code(value: str) -> str: # 換行壓成空格、反引號換成 ',以免行內程式碼提前結束;空值換成 - text = " ".join(value.split()).replace("`", "'") or "-" return f"`{_slack_escape(text)}`"
def _slack_escape(text: str) -> str: return text.replace("&", "&").replace("<", "<").replace(">", ">")空值會換成 -。一對空的反引號在 Slack 上什麼都不會顯示,看起來像訊息壞掉了:
不處理: *Job ID*: ``Slack: Job ID: // 後面什麼都沒有
換成 -: *Job ID*: `-`Slack: Job ID: - // - 顯示在行內程式碼框裡在程式碼區塊裡,值裡面如果有三個連續的反引號,區塊就會提前結束,所以會換成三個單引號。
自訂格式的 description 上限是 8,000 個字元。由於跳脫後的值最長可能會膨脹為原本的五倍(& 會變成 &),所以每個程式碼區塊會在跳脫之後截斷到 2,000 個字元以內。被截斷的區塊後面會加上一行提示,請讀者參閱電子郵件。
電子郵件裡永遠是完整的內容。
總結
工作流的錯誤警報現在除了電子郵件,也會送到 Slack,而每個警報來源依然只呼叫一次 Publish。
- 除了 CloudWatch 警示這類 Amazon Q Developer 支援的 AWS 事件,其他訊息都要用它的自訂通知 JSON 送出。純文字訊息會被丟棄,只會在 us-east-1 的日誌裡留下
Event received is not supported。 MessageStructure=json能讓每一種訂閱協定收到各自的內容。default把純文字送到電子郵件,https把 JSON 送到 Amazon Q Developer。- 每則警報先建立一個
Notice,再由publish_notice()產生電子郵件和 Slack 兩個版本。檔名和檔案內容放在只給電子郵件用的欄位,就不會出現在 Slack。 - mrkdwn 沒有
_和*的跳脫方式,所以 Slack 訊息裡的每個值都用反引號包起來。然而&、<和>在反引號裡依然會被 Slack 當成標記,所以要另外跳脫。 - 在討論串 ID 裡加上日期,就能讓同一個檔案在一天內的失敗集中在一個討論串,並在失敗再次發生的那天開一個新的討論串。
- 把日誌層級設為
ERROR,訊息內容就不會留在 us-east-1 的日誌群組裡。



