Amazon Q Developer で SNS のアラートを Slack に届ける — 1 通の SNS メッセージで、サブスクリプションのプロトコルごとに本文を分ける
Amazon Q Developer はプレーンテキストの SNS メッセージを捨てます。MessageStructure=json で publish すると、1 回の呼び出しでメールにはプレーンテキスト、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 つを指定します。
- Slack チャンネル:アラートを受け取るチャンネル。1 つのチャンネル設定に 1 つだけ指定します。
- SNS トピック:このチャンネルに通知を流すトピック。複数指定できます。
- IAM ロール:チャンネルで入力されたコマンドを実行するときのロール。
チャンネル設定を作ると、Amazon Q Developer が各トピックに HTTPS でサブスクライブします。トピックにもともとあったメールのサブスクリプションはそのまま残ります。
手作業が残る手順は 2 つあります。
- AWS のアプリを承認する:Slack ワークスペースにアクセスできる人が OAuth 画面で承認します。この画面は Amazon Q Developer のコンソールから開きますが、そのコンソールは米国東部(オハイオ)でしか動きません。
- プライベートチャンネルに招待する:プライベートチャンネルでは
/invite @Amazon Qと入力します。これをしないと、そのチャンネルには何も届きません。
それ以外はすべて CDK で書けます。
aws-cdk-lib/aws-chatbot の SlackChannelConfiguration には、省略できる role プロパティがあります。下のコードは role を指定していないので、CDK が信頼ポリシーだけを持ち権限の無いロールを自動で作ります。私はその上に ReadOnlyAccess をガードレールとして付けました。ガードレールは、ロールの権限にかかわらず、チャンネルで実行するコマンドができることの上限を決める IAM ポリシーです。
このチャンネルはアラートを受け取るだけです。チャンネルで @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,});スタックは東京リージョンにあります。Amazon Q Developer のコンソールはオハイオでしか動きませんが、チャンネル設定は米国用のスタックを別に作らなくても東京のスタックからデプロイできました。
プレーンテキストの SNS メッセージが Slack に届かなかった理由
Amazon Q Developer はプレーンテキストの SNS メッセージを捨て、ログを 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 を持たせます。
{ "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 でサブスクライブしているので、こちらの本文を受け取ります。
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 が届きます。
https キーの本文は、Amazon Q Developer に限らず HTTPS のサブスクライバーすべてに届きます。
今のところ HTTPS のサブスクライバーは Amazon Q Developer だけです。
あとから同じトピックに Webhook をサブスクライブすると、その Webhook にもカスタム通知の JSON が届きます。そのため、https キーの横に、この点を注意するコメントを残しました。
1 つの Notice を、メール用と Slack 用に書き分ける
パイプラインでアラートを publish する箇所は、大きく 2 種類に分けられます。
- 試行が 1 回失敗したとき:翻訳などのジョブが失敗し、このあとリトライされる場合です。
- リトライを使い切ったとき:ジョブがリトライを使い切ってデッドレターキューに入り、その通知処理がアラートを出します。
私はどの箇所でも Notice を 1 つ組み立て、publish_notice() に渡すようにしました。publish_notice() はその Notice を、メール用と Slack 用の 2 通りに書き分けます。
@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 つあります。
target:メールの件名にだけ出る文字列。ファイル名など。email_fields:メール本文にだけ出る「名前:値」の項目。「ファイル:report_v2.docx」など。email_blocks:メール本文にだけ出るまとまったテキスト。スプレッドシートの列見出しや元のキューメッセージなど。
slack_notice() はこの 3 つを読まないので、これらの情報は Slack に出ません。省いた情報がある場合は、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 の末尾に日本時間の日付を付けるようにしました。こうすると、翌日に同じ失敗が再発したときは新しいスレッドが始まります。
payload["metadata"] = { "threadId": f"{notice.thread_id}#{_today()}", # box#123456#2026-11-05 "summary": _slack_escape(notice.heading),}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」というフッターで終わる。どちらにもファイル名は出ていない。](/_astro/slack-thread@2x.DwcBxE3y_ZIGFq.webp)
Slack 独自の mrkdwn 記法に対応する
textType: "client-markdown" は、title と description のテキストが Slack の mrkdwn であることを Amazon Q Developer に伝えます。mrkdwn は Slack 独自のマークアップで、*太字* や _斜体_ のように書式を付けます。
Slack の API で直接投稿するなら、plain_text のテキストオブジェクトや mrkdwn: false で書式を無効にできます。しかし Amazon Q Developer のカスタム通知の形式には対応するフィールドが無いので、無効にできません。
*v2* は、Amazon Q Developer を経て Slack に届くとアスタリスクが消え、v2 が太字になる。値はすべてバッククォートで囲み、Slack でインラインコードかコードブロックとして表示させます。どちらの中でも mrkdwn は効きません。
fields はインラインコードとして、blocks はコードブロックとして表示されます。
それでも &、<、> の 3 つはバッククォートの中でもエスケープします。Slack はこの 3 文字をリンクやメンション(<@U123> など)の記法に使っていて、インラインコードやコードブロックの中でも例外ではないからです。そこで、これを処理する関数を 2 つ書きました。
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: - // - がインラインコードの枠に入るコードブロックの中では、値にバッククォートが 3 つ続いているとブロックが途中で終わってしまうので、シングルクォート 3 つに置き換えます。
カスタム形式の description の上限は 8,000 文字です。エスケープすると値は最大で 5 倍に膨らむ(& が & になる)ので、各コードブロックはエスケープしたあとで 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 のロググループに残りません。



