# 我用 Amazon Q Developer 把 SNS 警報送進 Slack — 只發布一則 SNS 訊息，依訂閱協定送出不同的內容

> Amazon Q Developer 會丟棄純文字的 SNS 訊息。發布時加上 MessageStructure=json，同一則訊息就能讓電子郵件收到純文字、讓 Slack 收到自訂通知。

- Source: https://oharu121.com/zh-tw/blog/sns-slack-alerts-amazon-q-developer-messagestructure-json/
- Published: 2026-11-08T10:38:06+09:00
- Tags: AWS, Amazon Q Developer, 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）為單位設定。一個頻道組態包含三樣東西：

1. **Slack 頻道**：接收警報的頻道，一個頻道組態只對應一個頻道。
2. **SNS 主題**：負責把通知送進這個頻道的主題，可以指定多個。
3. **IAM role**：在頻道裡輸入的指令會以這個 role 的身分執行。

建立頻道組態後，Amazon Q Developer 會以 HTTPS 訂閱每一個主題。主題原本的電子郵件訂閱則維持不變。

有兩個步驟仍然需要手動完成：

1. **核准 AWS 應用程式**：要由能存取該 Slack 工作區的人在 OAuth 畫面上核准。這個畫面要從 Amazon Q Developer 主控台開啟，而這個主控台只能在美國東部（俄亥俄）使用。
2. **邀請到私人頻道**：如果是私人頻道，還要在該頻道輸入 `/invite @Amazon Q`，否則私人頻道什麼都收不到。

其餘的部分全都可以用 CDK 完成。
`aws-cdk-lib/aws-chatbot` 的 `SlackChannelConfiguration` 有一個可省略的 `role` 屬性。下面的程式碼沒有指定 `role`，所以 CDK 會自動建立一個只有 trust policy、沒有任何權限的 role。我另外把 `ReadOnlyAccess` 設為 guardrail。guardrail 是一種 IAM 政策，不論 role 有什麼權限，頻道裡的指令最多只能做到 guardrail 允許的範圍。

**這個頻道只負責接收警報**。即使在頻道裡對 `@Amazon Q` 輸入指令，也無法變更帳戶裡的任何東西。

```ts title="core-stack.ts"
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。

> **小心喔**
>
> **INFO 層級的日誌會把每則訊息的內容複製到 us-east-1**
>
> 把 `loggingLevel` 設為 `INFO` 時，Amazon Q Developer 會把收到的每一則訊息連同內容寫進 us-east-1 的日誌群組 `/aws/chatbot/<configuration name>`，不論主題位於哪個區域都一樣。
> CDK 的 `logRetention` 預設是 `INFINITE`，所以警報內容會無限期留在另一個區域。
> 設為 `ERROR` 就不會留下訊息內容。

## 為什麼純文字的 SNS 訊息送不到 Slack？

**Amazon Q Developer 會丟棄純文字的 SNS 訊息**，而且只會留下一行日誌：

```text title="/aws/chatbot/<configuration name> (us-east-1)"
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`：

```json
{
  "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 訂閱的。

```python title="notifier.py"
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`。

*Figure — FanOut: 一則 SNS 訊息以純文字送到電子郵件，以自訂通知的 JSON 送到 Amazon Q Developer。送到 Amazon Q Developer 的純文字只會被丟棄。*

**`https` key 的內容會送到每一個 HTTPS 訂閱者，並不只是 Amazon Q Developer**。
目前唯一的 HTTPS 訂閱者是 Amazon Q Developer。
如果之後有 Webhook 訂閱了同一個主題，這個 Webhook 也會收到自訂通知的 JSON，所以我在 `https` key 旁邊留了一行註解提醒這件事。

## 同一個 Notice，分別產生電子郵件與 Slack 的版本

工作流裡會發布警報的地方，主要分成兩類：

1. **單次嘗試失敗**：翻譯之類的工作執行失敗，但之後還會重試。
2. **重試次數用盡**：工作用完了重試次數、進入 dead-letter queue，由通知程式發出警報。

> **話說**
>
> **dead-letter queue 收的是重試用盡的訊息**
>
> dead-letter queue（DLQ）是另外的一個佇列。佇列裡的訊息一直處理失敗、重試到上限之後，就會被移到這裡，之後不會再自動重試。這個工作流會在工作進入 dead-letter queue 時發出 🚨 的警報，也就是 dead-letter 通知。

**我讓這些地方都先建立一個 `Notice`，再交給 `publish_notice()`**，由它把同一個 `Notice` 產生成電子郵件和 Slack 兩個版本。

```python title="notifier.py"
@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` 有三個只給電子郵件用的欄位：

1. **`target`**：只出現在電子郵件主旨裡的文字，例如檔名。
2. **`email_fields`**：只出現在電子郵件內文裡的「名稱：值」，例如「檔案：report_v2.docx」。
3. **`email_blocks`**：只出現在電子郵件內文裡的整段文字，例如試算表的欄位標題或原始的佇列訊息。

`slack_notice()` 不讀這三個欄位，所以這些資訊不會出現在 Slack。如果有資訊因此被省略，Slack 訊息最後會加上一行，說明細節請見電子郵件。

*Figure — TwoRenderings: 同一個 Notice 分別做成電子郵件和 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 後面加上日本時間的日期。這樣一來，如果同樣的失敗隔天又發生，就會開啟一個新的討論串：

```python title="notifier.py"
payload["metadata"] = {
    "threadId": f"{notice.thread_id}#{_today()}",   # box#123456#2026-11-05
    "summary": _slack_escape(notice.heading),
}
```

> **話說**
>
> **討論串的時間範圍可以在頻道偏好設定裡修改**
>
> 這個 2 天是頻道偏好設定裡的「Start new thread after」，在頻道裡輸入 `@Amazon Q preferences` 就能修改。這個設定作用在整個頻道，所以我沒有改它，而是在 ID 裡加上日期。

回覆送達時，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」頁尾結束。兩則訊息都沒有出現檔名。](./_images/slack-thread@2x.webp)

*同一個檔案每次嘗試的失敗和當次的 dead-letter 通知集中在同一個討論串，兩則都沒有出現檔名。通知的標籤是英文，Slack 本身的介面是日文。*

## 對應 Slack 特有的 mrkdwn 語法

`textType: "client-markdown"` 告訴 Amazon Q Developer，`title` 和 `description` 裡的文字是 Slack 的 mrkdwn。mrkdwn 是 Slack 自己的標記語法，例如 `*粗體*` 和 `_斜體_`。

直接用 Slack 的 API 發訊息時，可以用 `plain_text` 文字物件或 `mrkdwn: false` 關閉格式。但 Amazon Q Developer 的自訂通知格式沒有對應的欄位，所以無法關閉。

*Figure — MrkdwnRendering: 檔名裡的 `*v2*` 經過 Amazon Q Developer 送到 Slack 後，星號不見了，v2 變成粗體。*

**每個值都用反引號包起來，讓 Slack 顯示成行內程式碼或程式碼區塊，因為 mrkdwn 在這兩種格式裡不會生效**。
`fields` 會顯示成行內程式碼，`blocks` 則顯示成程式碼區塊。

但即使包在反引號裡，`&`、`<` 和 `>` 還是要跳脫，因為 Slack 用這三個字元來標記連結和提及（例如 `<@U123>`），即使在程式碼或程式碼區塊裡也不例外。因此我寫了兩個函式來處理這些情況：

```python title="notifier.py"
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("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
```

空值會換成 `-`。一對空的反引號在 Slack 上什麼都不會顯示，看起來像訊息壞掉了：

```text title="Job ID 是空字串時"
不處理：  *Job ID*: ``
Slack：   Job ID:          // 後面什麼都沒有

換成 -：  *Job ID*: `-`
Slack：   Job ID: -        // - 顯示在行內程式碼框裡
```

在程式碼區塊裡，值裡面如果有三個連續的反引號，區塊就會提前結束，所以會換成三個單引號。

自訂格式的 `description` 上限是 8,000 個字元。由於跳脫後的值最長可能會膨脹為原本的五倍（`&` 會變成 `&amp;`），所以每個程式碼區塊會在跳脫之後截斷到 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 的日誌群組裡。

## 參考連結

- [Custom notifications using Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/custom-notifs.html)
- [Amazon SNS API Reference：Publish（包括 `MessageStructure`）](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html)
- [Slack：Formatting message text（包括哪些字元必須跳脫）](https://docs.slack.dev/messaging/formatting-message-text)
- [AWS CDK：`aws-cdk-lib/aws-chatbot` 模組](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_chatbot-readme.html)
