# Amazon Q Developer で SNS のアラートを Slack に届ける — 1 通の SNS メッセージで、サブスクリプションのプロトコルごとに本文を分ける

> Amazon Q Developer はプレーンテキストの SNS メッセージを捨てます。MessageStructure=json で publish すると、1 回の呼び出しでメールにはプレーンテキスト、Slack にはカスタム通知を送れます。

- Source: https://oharu121.com/ja/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 につなげられます。そこで本番に導入する前に、自分のワークスペースで試してみました。

**CloudWatch アラームは Slack に届きましたが、自分のコードが publish したメッセージはすべて黙って捨てられていました**。Amazon Q Developer が受け付けるのは、独自のカスタム通知の JSON だけだからです。

解決策は、**`MessageStructure=json` を付けて SNS メッセージを 1 通だけ publish すること**です。メールにはプレーンテキストの本文を、Slack にはカスタム通知の JSON を届けられます。
どのアラートの送信元も `Publish` の呼び出しは 1 回のままで、CloudWatch アラームもこれまでどおり Slack に届きます。

## アラートが Slack に届くまで

Amazon Q Developer in chat applications は、**チャンネル設定**（channel configuration）の単位で設定します。チャンネル設定には、次の 3 つを指定します。

1. **Slack チャンネル**：アラートを受け取るチャンネル。1 つのチャンネル設定に 1 つだけ指定します。
2. **SNS トピック**：このチャンネルに通知を流すトピック。複数指定できます。
3. **IAM ロール**：チャンネルで入力されたコマンドを実行するときのロール。

チャンネル設定を作ると、Amazon Q Developer が各トピックに HTTPS でサブスクライブします。トピックにもともとあったメールのサブスクリプションはそのまま残ります。

手作業が残る手順は 2 つあります。

1. **AWS のアプリを承認する**：Slack ワークスペースにアクセスできる人が OAuth 画面で承認します。この画面は Amazon Q Developer のコンソールから開きますが、そのコンソールは米国東部（オハイオ）でしか動きません。
2. **プライベートチャンネルに招待する**：プライベートチャンネルでは `/invite @Amazon Q` と入力します。これをしないと、そのチャンネルには何も届きません。

それ以外はすべて CDK で書けます。
`aws-cdk-lib/aws-chatbot` の `SlackChannelConfiguration` には、省略できる `role` プロパティがあります。下のコードは `role` を指定していないので、CDK が信頼ポリシーだけを持ち権限の無いロールを自動で作ります。私はその上に `ReadOnlyAccess` をガードレールとして付けました。ガードレールは、ロールの権限にかかわらず、チャンネルで実行するコマンドができることの上限を決める IAM ポリシーです。

**このチャンネルはアラートを受け取るだけです**。チャンネルで `@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,
});
```

スタックは東京リージョンにあります。Amazon Q Developer のコンソールはオハイオでしか動きませんが、チャンネル設定は米国用のスタックを別に作らなくても東京のスタックからデプロイできました。

> **気を付けて**
>
> **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 メッセージを捨て**、ログを 1 行残すだけです。

```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 は、CloudWatch アラームのように対応している AWS サービスの通知なら自分で整形します。それ以外のメッセージには、カスタム通知の形式を求めます。
カスタム通知は 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」という固定のフッターが付きます。この形式には、フッターを消すフィールドがありません。

## 1 通のメッセージで、サブスクリプションのプロトコルごとに本文を分ける

**`MessageStructure=json` を使うと、1 回の `Publish` 呼び出しでサブスクリプションのプロトコルごとに別の本文を送れます**。
このとき `Message` は JSON オブジェクトになり、キーがプロトコル名、値が文字列です。
`default` は必須で、専用のキーが無いプロトコルすべてに使われます。`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 なので、2 回エンコードされます。
メールにはこれまでどおり `default` の本文と `Subject` が届きます。

*Figure — FanOut: 1 通の SNS メッセージが、メールにはプレーンテキストとして、Amazon Q Developer にはカスタム通知の JSON として届く。Amazon Q Developer に送ったプレーンテキストは捨てられる。*

**`https` キーの本文は、Amazon Q Developer に限らず HTTPS のサブスクライバーすべてに届きます**。
今のところ HTTPS のサブスクライバーは Amazon Q Developer だけです。
あとから同じトピックに Webhook をサブスクライブすると、その Webhook にもカスタム通知の JSON が届きます。そのため、`https` キーの横に、この点を注意するコメントを残しました。

## 1 つの Notice を、メール用と Slack 用に書き分ける

パイプラインでアラートを publish する箇所は、大きく 2 種類に分けられます。

1. **試行が 1 回失敗したとき**：翻訳などのジョブが失敗し、このあとリトライされる場合です。
2. **リトライを使い切ったとき**：ジョブがリトライを使い切ってデッドレターキューに入り、その通知処理がアラートを出します。

> **ちなみに**
>
> **デッドレターキューにはリトライを使い切ったメッセージが入る**
>
> デッドレターキュー（DLQ）は別のキューです。処理に失敗し続けたメッセージは、リトライの上限に達するとここへ移され、それ以降は自動でリトライされません。このパイプラインは、ジョブがデッドレターキューに入ったときに 🚨 のアラート（デッドレターキューの通知）を出します。

**私はどの箇所でも `Notice` を 1 つ組み立て、`publish_notice()` に渡すようにしました**。`publish_notice()` はその `Notice` を、メール用と Slack 用の 2 通りに書き分けます。

```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` には、メールでしか使わないフィールドが 3 つあります。

1. **`target`**：メールの件名にだけ出る文字列。ファイル名など。
2. **`email_fields`**：メール本文にだけ出る「名前：値」の項目。「ファイル：report_v2.docx」など。
3. **`email_blocks`**：メール本文にだけ出るまとまったテキスト。スプレッドシートの列見出しや元のキューメッセージなど。

`slack_notice()` はこの 3 つを読まないので、これらの情報は Slack に出ません。省いた情報がある場合は、Slack のメッセージの最後に、詳細はメールにあると一行添えます。

*Figure — TwoRenderings: 同じ Notice をメールと Slack のメッセージにしたもの。件名とファイル名の行はメールにしか無い。*

`next_steps` はカスタム形式の `nextSteps` に対応し、Slack では「Next steps:」というラベルの下に箇条書きで表示されます。
`severity` は Slack のタイトルの絵文字を決めます。1 回の試行が失敗しただけなら ❌、リトライを使い切ったジョブなら 🚨 になります。

### `threadId` で、1 つのファイルの失敗を 1 日 1 つのスレッドにまとめる

`thread_id` は `metadata.threadId` に対応します。Amazon Q Developer は、以前と同じ ID のメッセージが届くと、それをスレッドへの返信として投稿します。
私はジョブのキーをこの ID に使っています（`box#123456` のように、元のサービスとファイル ID からできています）。そのため、あるファイルの試行ごとの失敗と、デッドレターキューの通知が 1 つのスレッドにまとまります。

**Amazon Q Developer は、既定では 2 日以内に届いた同じ ID のメッセージを 1 つのスレッドにまとめます**。そこで `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 に日付を入れることにしました。

`summary` は、返信が届いたときに Amazon Q Developer がスレッドの最初のメッセージに **Latest Update** として追加する行です。これで、スレッドを開かなくてもチャンネル上で最新の状態がわかります。

![Amazon Q Developer が投稿した Slack のスレッド。最初のメッセージは赤いバツ印と「[prod] Translation failed」というタイトルで、「[prod] Translation failed (retries used up)」と書かれた Latest Update の行、インラインコードで表示されたサービス・ファイル ID・ジョブ ID、コードブロックで表示された理由、Next steps の箇条書きが並ぶ。1 件だけある返信はサイレンと「[prod] Translation failed (retries used up)」というタイトルで、同じファイル ID、トリガー、時刻、返信自身の次の対応が並ぶ。最初のメッセージは「Custom notification delivered by Amazon Q Developer」というフッターで終わる。どちらにもファイル名は出ていない。](./_images/slack-thread@2x.webp)

*あるファイルの試行ごとの失敗とデッドレターキューの通知が、1 つのスレッドにまとまっている。どちらにもファイル名は無い。通知のラベルは英語で、Slack 自体の画面は日本語になっている。*

## Slack 独自の mrkdwn 記法に対応する

`textType: "client-markdown"` は、`title` と `description` のテキストが Slack の mrkdwn であることを Amazon Q Developer に伝えます。mrkdwn は Slack 独自のマークアップで、`*太字*` や `_斜体_` のように書式を付けます。

Slack の API で直接投稿するなら、`plain_text` のテキストオブジェクトや `mrkdwn: false` で書式を無効にできます。しかし Amazon Q Developer のカスタム通知の形式には対応するフィールドが無いので、無効にできません。

*Figure — MrkdwnRendering: ファイル名の `*v2*` は、Amazon Q Developer を経て Slack に届くとアスタリスクが消え、v2 が太字になる。*

**値はすべてバッククォートで囲み、Slack でインラインコードかコードブロックとして表示させます。どちらの中でも mrkdwn は効きません**。
`fields` はインラインコードとして、`blocks` はコードブロックとして表示されます。

それでも `&`、`<`、`>` の 3 つはバッククォートの中でもエスケープします。Slack はこの 3 文字をリンクやメンション（`<@U123>` など）の記法に使っていて、インラインコードやコードブロックの中でも例外ではないからです。そこで、これを処理する関数を 2 つ書きました。

```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: -        // - がインラインコードの枠に入る
```

コードブロックの中では、値にバッククォートが 3 つ続いているとブロックが途中で終わってしまうので、シングルクォート 3 つに置き換えます。

カスタム形式の `description` の上限は 8,000 文字です。エスケープすると値は最大で 5 倍に膨らむ（`&` が `&amp;` になる）ので、各コードブロックはエスケープしたあとで 2,000 文字以内に切り詰めます。切り詰めたブロックの後ろには、メールを参照するよう促す一行を添えます。
**メールには常に全文が載ります**。

## まとめ

パイプラインのエラーアラートは、メールに加えて Slack にも届くようになりました。どのアラートの送信元も、`Publish` の呼び出しは 1 回のままです。

- CloudWatch アラームのように Amazon Q Developer が対応している AWS のイベント以外は、カスタム通知の JSON で送ります。プレーンテキストは捨てられ、us-east-1 のログに `Event received is not supported` が残るだけです。
- **`MessageStructure=json` を使うと、サブスクリプションのプロトコルごとに本文を分けられます**。`default` でメールにプレーンテキストを、`https` で Amazon Q Developer に JSON を届けます。
- アラートは `Notice` として 1 回だけ組み立て、`publish_notice()` でメール用と Slack 用に書き分けます。ファイル名やファイルの内容はメール専用のフィールドに入れるので、Slack には出ません。
- mrkdwn には `_` と `*` のエスケープが無いので、Slack のメッセージに入れる値はすべてバッククォートで囲みます。ただし `&`、`<`、`>` はバッククォートの中でも Slack が記法として読むので、別にエスケープします。
- スレッド ID に日付を入れると、1 つのファイルの失敗が 1 日のあいだ同じスレッドにまとまり、失敗が再発した日には新しいスレッドが始まります。
- ログレベルを `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)
