amazon-eventbridge-event-bus

新しい EventBridge カスタムイベントバスを使用した開発

概要

新しい EventBridge カスタムイベントバスは、イベントをルーティングして保持します。2 つの API のいずれかを使って発行し、サブスクライバーはイベントをフィルタリングし、必要に応じて変換して、一致した各イベントを 1 つのターゲットに配信します。

フィルター、変換器、またはターゲットのパラメーターを記述する前に、第 5 章と第 6 章をお読みください。 2 つの発行 API ではペイロードの形式が異なるため、一方に合わせて記述した式は、もう一方に対してはエラーもなく一致しません。

発行メトリクスはデフォルトで有効になっているため、イベントがバスに届いたかどうかはいつでも確認できます。サブスクライバーのログはデフォルトで無効になっているため、配信のデバッグを始める前に有効にしてください（第 18 章）。

次の環境での利用が最適です： AWS MCP サーバー。このスキルで CLI 呼び出しを実行する際に推奨されます。監査ログ付きのサンドボックス環境で実行されます。標準的な AWS CLI アクセスでも、すべてのガイダンスを利用できます。

表記規則

このスキルにおける MUST、MUST NOT、SHOULD、MAY というキーワードは、RFC 2119 の説明に従って解釈してください。これらのキーワードは、誤った手順を選ぶと設定が壊れるか、イベントが気付かれないまま失われるような判断手順にのみ登場します。MUST は絶対的な要件、SHOULD は特別な理由があれば従わない選択もできる強い推奨、MAY は実際に選択可能な事項を示します。

それ以外は通常の説明です。サービスの動作を述べる文にキーワードが含まれないのは、あなたへの指示ではなく事実だからです。

このスキルを使用しない場合

このスキルは、新しいカスタムイベントバス、つまり eventsv2 CLI および eventbridgev2 SDK クライアントで利用するサービスのみを対象としています。以下は対象外です。

• 従来の EventBridge：ルール、ターゲット、アーカイブ、および AWS::Events::Rule のイベントパターンを使用する events API を指します。この 2 つのサービスは events: IAM 名前空間と一部の用語を共有しており、だからこそ混同しやすくなっています。ルールを記述している場合、新しいバスを使っているわけではありません。移行中であれば、第 3 章で各概念の対応関係を確認できます。
• EventBridge Pipes、Scheduler、Schemas（従来のスキーマレジストリとその検出機能）。API が異なります。
• Firehose サービス自体の設定（バッファリングのヒントやレコードの変換など）。Firehose 配信ストリームは有効なサブスクライバーターゲットです。その側面については第 9 章で説明します。

トリガーの例

1. 「このサブスクライバーには、500 ドルを超える注文だけが届くようにフィルターを記述してください。」
2. 「プロデューサーには PUBLISHED と表示されますが、キューに何も表示されません。何を確認すればよいですか？」
3. 「Protobuf ペイロードには PutEvents と PutRawEvents のどちらを使うべきですか？」
4. 「過去 2 日間のすべてのイベントを再処理するサブスクライバーを設定してください。」
5. 「イベントから顧客 ID を取り出して DynamoDB の putItem に渡す JSONata 式を記述してください。」

ガードレール — このスキルのファイルの場所（MCP 対ローカルインストール）

このスキルは 2 通りの方法で読み込むことができ、それぞれスキルに同梱されたファイルの参照先が異なります。参照ファイルを読む前に、スキルがどちらの方法で読み込まれたかを確認してください。

• AWS MCP の retrieve_skill ツールから読み込まれた場合： スキルはローカルファイルシステムにインストールされていません。各参照ファイルは file パラメーターを指定して retrieve_skill で取得する必要があります（例：file="references/setup-walkthroughs.md"）。これらのパスはディスク上に存在しないため、ローカルで file_read を使ってはいけません。
• ローカルにインストールされている場合（例：.kiro/skills/amazon-eventbridge-event-bus/ または ~/.claude/skills/amazon-eventbridge-event-bus/）：相対パスを使用して、ローカルのスキルディレクトリからファイルを読み取ってください。

この区別が適用されるのは、スキルに同梱されたファイルだけです。ユーザーデータとセッションの成果物は、常にユーザーの作業ディレクトリから読み取り、そこに書き込んでください。retrieve_skill を通じて顧客データを取得または書き込みしないでください。

参照ファイル

以下の章には、判断事項と失敗パターンが記載されています。詳細はこれらのファイルにあります。作業内容が該当するファイルを読み込み、デフォルトですべてを読み込まないでください。

ファイル	読み込むタイミング
setup-walkthroughs.md	1 つのアカウント内、または AWS RAM を使ってアカウント間で共有し、前提条件の確認から後片付けまで、バスを一通り構築するとき
code-samples.md	個別の CLI または SDK 呼び出し（Python、Java、TypeScript）を作成するとき：バスとサブスクライバーの作成、いずれかの API を使った発行、バイナリペイロード、再生、クロスアカウントの許可、ウェイター、エントリごとの結果、スロットリング時のバックオフ
filters-and-expressions.md	イベントを参照するフィルターパターン、JSONata 式、またはターゲットパラメーターを作成するとき。完全な形式の、配信される両方のエンベロープを確認するとき
target-configuration.md	サブスクライバーのターゲットを設定するとき。特にユニバーサルターゲットの場合
target-contract.md	実際の CreateSubscriber 呼び出しを作成するとき：必須フィールド、ターゲットタイプごとの実動作する例、リテラルと JSONata の違い、配信エラーの分類
migrating-from-classic.md	従来の EventBridge から移行するとき、移行手順を計画するとき、または従来の慣習が新しいバスの設定ミスにつながるとき
event-sources.md	イベントソースを使って AWS サービスイベントやパートナーイベントをバスに送るとき、または転送されたイベントが届かない、あるいはフィルターに一致しないとき
provisioning-and-state.md	バスを作成または更新するとき、またはリソースが予期しない状態のままになっているとき
delivery-troubleshooting.md	発行したイベントが届かないとき、または配信数を正確にカウントするテスト環境を構築するとき
authorization.md	IAM ポリシーまたはバスのリソースポリシーを作成するとき、クロスアカウントアクセスを確認するとき、またはイベントをバスに転送するとき
replay-and-recovery.md	新しいイベントではなく履歴を読み取るとき、一時停止または再開するとき、または再生が機能していないように見えるとき
observability.md	メトリクス、アラーム、または提供されるログ配信を設定するとき、配信ログを読むとき、アカウント間を監視するとき
schema-registries.md	Avro、Protobuf、または JSON 以外の形式を発行するとき、受け入れられるコンテンツタイプを確認するとき、Kafka と並行して実行するとき
cloudevents.md	CloudEvents を発行または利用するとき、または CloudEvents の属性でフィルタリングするとき
security-and-sharing.md	バスを暗号化するとき、クロスアカウントで共有するとき、またはタグを設定するとき
cost-and-quotas.md	課金の仕組み、アカウント間の費用負担、コストを抑えるためのイベント整形、またはスロットリングへの対処を確認するとき
infrastructure-as-code.md	CloudFormation テンプレートを作成するとき、アカウント間でスタックを分割するとき、またはプライベート接続を設定するとき

---

1. 3 つのリソース

イベントバス。 イベントの発行先です。イベントをルーティングし、保持します。

サブスクライバー。 受信するイベントと送信先を、1 つのリソースで指定します。イベントバスを監視し、フィルターに一致するイベントを保持し、必要に応じて各イベントを変換して、1 つのターゲットにのみ配信します。1 つのイベントを複数のターゲットに送信するには、同じイベントバスに複数のサブスクライバーを作成します。

イベントソース。 AWS サービスイベントまたはパートナー／SaaS ソースのいずれかを、イベントバスに取り込むためのマネージドフィードです。

名前と識別子：

• イベントバス ARN とサブスクライバー ARN は、どちらも名前の後にサービスが生成した ID が付きます。 arn:aws:events:us-east-1:111122223333:event-busv2/my-bus/exampleid0123456789abcdef。 名前ではなく完全な ARN を保存してください。名前だけではリソースを特定できず、削除したイベントバスを同じ名前で再作成しても、別の ID が割り当てられるためです。
• イベントソース名は、イベントバスごとではなくアカウントごとに一意です。
• このサービスを識別する名前は 3 つあり、それぞれ一致しません。 CLI コマンドとエンドポイントホストは eventsv2 です（例：aws eventsv2 create-event-bus、eventsv2.{region}.amazonaws.com）。SDK クライアントは eventbridgev2 です。IAM アクションと ARN は、従来の EventBridge と共通の events です（例：events:PutEvents、arn:aws:events:...:event-busv2/...）。第 14 章を参照してください。

2. 永続ログを備えたルーター

イベントバスは各イベントを一致するサブスクライバーにルーティングし、設定された期間もイベントを保持します。この期間は、イベントバスごとに StorageConfiguration.RetentionPeriodInDays で設定します（1～365 日）。保持機能により、開始位置、処理の一時停止と再開、再生、そして今日作成したサブスクライバーによる昨日発行されたイベントの読み取りという、4 つの機能が可能になります。保持期間の範囲はイベントバスの作成時点で制限されるため、作成から間もないイベントバスでは、過去の比較的新しいタイムスタンプでも範囲外になることがあります。

3. 従来の EventBridge から移行する場合

従来のルールとそのターゲットは、新しいイベントバス上の 1 つのサブスクライバーに相当します。新しいイベントバスには、従来の EventBridge に相当するものがない概念が 4 つあります。イベントバス自体での保持、サブスクライバーの開始位置、バックログを伴う一時停止と再開、そしてペイロードモデルの異なる 2 つの発行 API です。最後の違いによりフィルターの記述方法が変わるため、従来のイベントパターンを変更せずに移行した場合、そのまま機能するのは PutEvents だけです。概念の対応関係、誤って引き継がれやすい習慣、段階的な移行手順については、 migrating-from-classic.md を参照してください。

4. AWS サービスおよびパートナーのイベントソース

イベントソースは、バスに接続するマネージドフィードです。宛先バスと起点を指定して作成すると、サービスが従来の EventBridge 側に転送を設定します。ロールも配信コードも必要ありません。マネージド経路では、サービス独自の ID が使われます。

Configuration は判別共用体であり、設定するバリアントは必ず 1 つだけです。

バリアント	起点	必須メンバー
AwsServiceEventsConfiguration	aws.s3 のような AWS サービス 1 つ	AwsService
PartnerEventsConfiguration	従来のパートナーイベントソース	PartnerEventSourceArn

どちらにも省略可能な Pattern があり、転送対象を絞り込みます。このパターンは従来のエンベロープに対して、従来側で評価されます。パターンに source キー、またはトップレベルの account や region を含めてはいけません。これらは、転送先をお客様のアカウントと起点に固定するために、サービス自身が設定します。

転送されたイベントは、従来のエンベロープ全体として届きます。 Data にその内容が格納され、ContentType は application/eventbridge+json です。コンテンツは $events.Data.detail にあり、ソースと detail-type は SystemMetadata の aws:Source と aws:DetailType に格納されます。そのため、従来のルールの source フィルターは引き継がれません。同等のフィルターは SYSTEM_METADATA フィルター {"aws:Source":["aws.s3"]} です。

AWS サービスまたはパートナーがイベントを生成したことを証明できるのは、この SystemMetadata の 2 つの値だけです。 どの publish 呼び出しでも、これらのキーを書き込むことはできません。生のペイロードでもエンベロープを完全に模倣できるため、ペイロードの source に対する DATA フィルターは、本物のイベントと同じように偽造イベントにも一致します。出所が重要な場合は、aws:Source でフィルタリングすることを推奨します。また、直接の PutEvents もキーを設定し、その値には aws. で始まらない独自の Source が使われるため、キーの有無ではなく値を照合しなければなりません。

EventBusArn は変更できません。復旧方法は失敗の状態によって異なります。CREATE_FAILED または UPDATE_FAILED からは、UpdateEventSource により従来側をお客様のレコードに再同期できます。一方、DELETE_FAILED から復旧する方法は、もう一度削除することだけです。

バス所有者が制御できるのは作成時です。 CreateEventSource は events:source 条件キーを使って宛先バスに対して認可されます。また、既存のフィードを停止するには、所有者が RevokeResource を使います（第 22 章）。前提条件、暗号化、デッドレター処理、および従来のアカウントに表示される内容については、event-sources.md を参照してください。

5. パブリッシュ API の選択

選択によってペイロードの形式が決まり、ペイロードの形式によって、その後に記述するすべてのフィルター、トランスフォーマー、ターゲットパラメーターが決まります。

	PutEvents	PutRawEvents
ペイロードフィールド	Detail、JSON 文字列	Data、base64 blob
ペイロードは JSON である必要があるか	はい	いいえ、任意の形式
エントリーごとに必須	Source、DetailType	Data、SystemMetadata
ContentType	受け付けません。サービスが application/eventbridge+json を設定します	必須。各エントリーの SystemMetadata 内に指定します
従来形式のフィールド	Resources、Time を使用可能	ありません
独自のメタデータ	なし	Metadata、最大 100 個のキー
順序付けと重複排除の入力値	SystemMetadata.EventGroupId、SystemMetadata.DeduplicationId	同じ 2 つのフィールド

従来形式のエンベロープを使用する JSON イベントには PutEvents を使います。バイナリまたは JSON 以外のペイロード、独自のメタデータキー、あるいは送信したとおりのペイロードを配信する場合は PutRawEvents を使います。

どちらもリクエスト内の各エントリーに対して、同じ順序で結果エントリーを 1 つずつ返すため、インデックスで対応付けます。それぞれに SuccessCode または ErrorCode と ErrorMessage が含まれます。SuccessCode は PUBLISHED または DEDUPLICATED で、DEDUPLICATED は成功であり、エラーではありません。 すべての成功を新しいイベントとして扱うコードでは、重複排除が配信として認識されてしまいます。

Avro または Protobuf のパブリッシュには、バスではなく各パブリッシュリクエストで指定するスキーマレジストリが必要です。間違った場所に設定されたレジストリでは、イベントがデコードされません。application/octet-stream にはレジストリは不要です。サービスはそのバイト列をまったくデコードしないためです （schema-registries.md）。

6. アドレス指定：各フィールドの場所

フィルター、トランスフォーマー、ターゲットパラメーターは共通のアドレス指定モデルを使いますが、2 つのパブリッシュ API では同じではありません。 すべてのイベントは、トップレベルの 3 つの名前、すなわち Data（ペイロード）、Metadata（独自のキー。PutRawEvents のみ）、SystemMetadata（サービスが割り当てるフィールドと順序付けフィールド）の下で配信されます。raw パブリッシュされたペイロードは Data に直接配置されますが、PutEvents のペイロードは従来形式のエンベロープ内の 1 レベル下にある detail に配置されます。そのため、同じフィールドでも、一方の API では $events.Data.m、もう一方では $events.Data.detail.m となります。間違った形式を指定してもエラーにはなりません。値が解決されず、フィルターは何にも一致せず、トランスフォーマーは何も出力しません。両方の API を使って 1 つのバスにパブリッシュする場合は、両方で機能する式を記述するか、トラフィックの種類ごとに異なるサブスクライバーを用意してください。両方に通用するアドレス指定形式はありません。すべての SystemMetadata フィールドを含む両方のエンベロープ全体については、filters-and-expressions.md を参照してください。

7. フィルタリング

サブスクライバーの FilterConfiguration には Filters のリストが格納され、イベントが配信されるには、リスト内のすべてのフィルターに一致する必要があります。フィルターは OR ではなく AND で結合されます。各フィルターには Pattern と Scope（DATA、METADATA、SYSTEM_METADATA）があり、スコープごとにフィルターは 1 つです。DATA パターンは第 6 章の形式に基づいて記述するため、1 つのパターンを両方のパブリッシュ API に使うことはできません。それぞれのパターンは一方の API でのみ正しく機能し、もう一方では何にも一致しないままです。作成時に FilterConfiguration を指定する必要はありません。指定のないサブスクライバーは、バス上のすべてのイベントを受信します。何にも一致しないフィルターは、故障したサブスクライバーと見分けがつかないため、ターゲットを観察して、一致するはずのケースと一致しないはずのケースを確認してください。

8. 変換

サブスクライバーの Transformer には3つの型があります。RAW（デフォルト）はペイロードのみを配信し、WITH_METADATA は3つの要素からなるエンベロープを配信し、JSONATA は式の評価結果を配信します。JSONata 式は {% %} の区切り文字で囲み、イベントを $events として参照します。参照方法は第6章とまったく同じです。ほとんどのスカラー型のターゲットパラメーターも、同じ形式で式を指定できます。一部のメンバーでは式を使用できず、リテラルを指定 しなければなりません。API Gateway のヘッダー名、メッセージ属性の BinaryValue、InvocationType が該当します。式の構文チェックは作成時にのみ行われるため、式の評価結果がわかるのは配信時です。式が例外をスローする、または何も評価されない JSONATA トランスフォーマーは、お客様側の不備による配信失敗となるため、テストする べきです。

9. ターゲットとそのパラメーターブロック

InvokeConfiguration には TargetArn、RoleArn、および ターゲットに一致するパラメーターブロックを最大1つ 指定します。ユニバーサルターゲットでは、そのブロックを必ず指定 しなければなりません。型指定されたブロックはすべて省略できます。従来型のバスと Firehose 配信ストリームはいずれも、ブロックを指定せずに使える有効なターゲットです。

サービスは ARN からターゲットの型を特定し、保存前に自身が管理する不変条件を検証します。具体的には、ブロックがターゲットに一致すること、ARN のリージョン、パーティション、アカウントが自身のものと一致すること、すべての式が解析できることです。ターゲット API 独自のパラメーター文法、値の範囲、識別子の上限、その API で必須となるメンバーは検証しません。これらはターゲット側の制約であるため、ターゲットが拒否するリクエストでも作成時には受け付けられ、配信時に失敗します。

1. ユニバーサルターゲットで必須のパラメーターブロックは指定しなければなりません。 型指定されたブロックは省略できます。KinesisParameters: {} は保存されますが、呼び出し時に Kinesis が PartitionKey の不足を報告します。
2. メッセージごとのフィールドに定数を指定してはなりません。定数の重複排除 ID を指定すると、ターゲットが最初のメッセージ以降をすべて破棄するためです。どちらの形式も、ターゲットの値の範囲、必須かどうか、FIFO への適用可否に照らした検証は行われないため、不正な値や値の不足は配信失敗となります。
3. ターゲットサービス独自のルールを確認するべきです。 リソースの存在、到達可能性、認可、エンベロープ化後のサイズ、API の必須フィールドは、配信時にターゲットによって適用されます。
4. ターゲット側で確認するべきです。PUBLISHED 応答は配信を意味せず、バッチ API からの HTTP 200 も配信を意味しません。バッチ API では、個々のエントリーが失敗していても HTTP 200 が返る場合があります。
5. テスト前にデッドレターキューを設定し、ログを有効にし、配信ロールにそのキューの sqs:SendMessage を許可しなければなりません。これを怠ると、失敗してもどこにも通知されないためです。

各ルールに違反した場合の動作、正確な拒否メッセージ、ターゲットごとのブロックについては、target-configuration.md を参照してください。呼び出し自体を書く前に、必須フィールドの一覧、ターゲットの型ごとに1つずつ示した動作する例、配信エラーの分類について target-contract.md を確認してください。

10. ユニバーサルターゲット

ユニバーサルターゲットは、中間関数を介さずに、サポートされている AWS API を直接呼び出します。ターゲット ARN の形式は固定です。

arn:{partition}:events:::aws-sdk:{service}:{apiAction}

作成時に問題を示すメッセージとともに失敗する、正しく指定すべき点が4つあります。apiAction は先頭が小文字のキャメルケースです（putItem）。service は SDK のサービス ID であり、常にわかりやすい名前とは限りません（Step Functions は sfn です）。UniversalTargetParameters.Input は必須で、API リクエストを JSON として、またはそれを生成する JSONata 式として指定します。また、BatchConfiguration も必須です。サービスの検証メッセージでは、ユニバーサルターゲットを「USI target」と略していますが、どちらも同じ意味です。

11. 順序制御と重複排除

順序制御はサブスクライバーのプロパティです。Type は UNORDERED（保証なし）または FIFO（イベントグループ内で順序を保証）で、イベントは公開時に SystemMetadata.EventGroupId によってグループ化されます。FIFO ターゲットはグループ ID に独自の長さ制限と文字数制限を適用します。配信できないイベントがあると、そのイベント自身のグループ内の後続イベントは滞留しますが、同じサブスクライバー上の他のグループの処理は継続するため、グループ ID は上限のある値にし、上限のない入力から導出しないでください。

重複排除は公開時に 2 つの方法で行われます。リクエストで DeduplicationConfiguration.DeduplicationType: CONTENT_BASED を指定するとイベント内容がハッシュ化されます。また、DeduplicationType の値は CONTENT_BASED のみです。独自のキーで重複排除するには、DeduplicationConfiguration を省略し、各エントリの SystemMetadata.DeduplicationId を設定します。どちらの場合も、重複として抑制されたイベントは SuccessCode: DEDUPLICATED を返します。

この 2 つの概念は分けて考えてください。バスレベルの重複排除は、イベントが受け付けられるかどうかを判定します。FIFO ターゲット独自の重複排除 ID はターゲットパラメーターブロックで設定し、そのターゲットが配信を受け付けるかどうかを判定します。異なるレイヤーにある別々のフィールドであり、後者はメッセージごとの値です（第 9 章、ルール 2）。

12. 再試行とデッドレター処理

RetryPolicy には 3 つのメンバーがあります。

メンバー	範囲	デフォルト
MaxRetryAttempts	0-185	5
MaxEventAgeInSeconds	60-86400	300
RetryStrategy	ALL	ALL

先に到達した方の制限で配信が停止し、それまでは失敗した配信が再試行されます。そのため、「何も届かなかった」という結論を出してよいのは、MaxEventAgeInSeconds の期間が経過した後だけです。

OnFailureConfiguration.Arn はデッドレター処理用の SQS キューを指定します。サポートされている宛先は SQS のみです。イベントソースは FIFO キューを指定すると拒否します。この場合、次のメッセージがそのまま表示されます。 OnFailureConfiguration.Arn must name a standard SQS queue: FIFO queues are not supported as EventSource dead-letter queues サブスクライバーでは FIFO キューが受け付けられるため、この点で 2 つのリソースの動作は異なります。さらに、考慮すべき制限が 2 つあります。デッドレターのレコードには失敗したイベントの ID とタイムスタンプが記録されますが、ペイロードは含まれないため、再生するにはイベントがまだ保持期間内にある必要があります。また、デッドレターキューには配信ロールが書き込みできなければなりません。そうでないと、失敗イベントの送信先がなく、通知もないままイベントが消失します。

13. 配信権限

InvokeConfiguration.RoleArn は、サービスがターゲットを呼び出すために引き受けるロールです。そのロールは呼び出し元のアカウントに属していなければならず（MUST）、信頼ポリシーでは events.amazonaws.com サービスプリンシパルを許可しなければなりません（MUST）。また、そのポリシーでは aws:SourceAccount と aws:SourceArn を条件に指定することが推奨されます（SHOULD）。ロールにはターゲットが必要とするアクション（sqs:SendMessage、sns:Publish、lambda:InvokeFunction、kinesis:PutRecords、states:StartExecution、またはユニバーサルターゲットが呼び出すアクション）と、デッドレターキューに対する sqs:SendMessage の権限が必要です。権限がなければ配信に失敗し、失敗レコードも書き込まれず、状況を観測できません。

CreateSubscriber は、このロールに対する iam:PassRole も適用します。そのため、渡すことのできないロールを指定すると、ターゲットの検証が実行される前に AccessDeniedException が発生します。この一覧には 4 つのアクションが記載されていません。Kinesis 配信では PutRecords、Firehose では PutRecordBatch が呼び出され、API Gateway には execute-api:Invoke、API の宛先には events:InvokeApiDestination が必要です。

ターゲット ARN は作成時に形式、タイプ、リージョン、パーティション、アカウントが検証されますが、存在や到達可能性は検証されません。形式が正しくても存在しない ARN は保存され、配信時に失敗します。

14. 認可：呼び出し元に必要な権限

第13章では、ターゲットを呼び出すために EventBridge が引き受けるロールについて説明しました。この章では、API にアクセスするために呼び出し元に必要な権限について説明します。

すべてのアクション名は events: です。 CLI コマンドとエンドポイントのホスト名は eventsv2 で、SDK クライアント名は eventbridgev2 ですが、IAM の名前空間は従来の EventBridge と共通の events です。IAM ポリシーに eventbridgev2: や eventsv2: を記述してはいけません。 どちらも存在するアクション名ではなく、どちらを記述してもポリシーはエラーなく受け付けられますが、権限は何も付与されません。直前に実行したコマンドからポリシーを作成し、eventsv2:PutEvents を許可するのが、この問題が起きる典型的なケースです。アクション名ごとの対応表は authorization.md にあります。

発行の認可は、エントリーごとにバス ARN に対して行われ、部分的な認可はありません。エントリーのいずれかが条件チェックに失敗すると、リクエスト全体が拒否されます。そのため、バッチの認可レベルは、最も認可が制限されたエントリーに左右されます。

サブスクライバーやイベントソースの作成はバスに対して認可されるため、バスがアカウント間の許可を与える場所になります。バスの所有者は、別のアカウントが何かをアタッチできるかどうかをここで決定します。

指定したロールでバスに転送する場合、認可は取り込み時にイベントごとに行われます。AWS またはパートナーからの実際のイベントには events:PutEvents が必要で、独自に発生させたイベントには events:PutRawEvents が必要です。両方の種類を運ぶフォワーダーには、両方のアクションを許可する必要があります。 片方だけを許可すると、ストリームの半分が警告なしに拒否されるためです。条件キー、作成時の各種チェック、取り消しの仕様については authorization.md を参照してください。

15. プロビジョニングとリソースの状態

バスの作成は非同期です。CreateEventBus は State: CREATING の状態で返り、その後バスが使用可能になります。手動でポーリングを実装するのではなく、ウェイターを使用してください。 ウェイターなら、失敗状態を検出するとすぐに終了し、タイムアウトまでポーリングを続けるのではなく StateReason を返します。

aws eventsv2 wait event-bus-active  --event-bus-arn "$BUS_ARN"

バスには7つの状態があり、重要な違いは2つの失敗状態の間にあります。UPDATE_FAILED は同じリソース上で復旧できますが、CREATE_FAILED はできません。 作成に失敗した場合に許可される操作は削除のみのため、そのバスを削除して再作成する必要があります。バスを削除する前に、サブスクライバーとイベントソースを削除してください。どちらかが残っているバスに対して DeleteEventBus を実行すると ResourceInUseException が返され、エラーメッセージには妨げとなっている種類が示されます。取り消し済みのサブスクライバーとイベントソースは削除を妨げません。

作成操作は ClientToken によって冪等になります。 CreateEventBus、CreateSubscriber、CreateEventSource はそれぞれトークンを受け付けます。同じトークンを指定して再試行すると、2つ目のリソースを作成するのではなく、元の結果が返されます。フィールドを省略すると、SDK は呼び出しごとに新しいトークンを生成するため、独自コードによる再試行では新しいリクエストが作成され、新しいトークンが割り当てられ、2つ目のリソースが作成されます。そのため、再試行がプロセス、キュー、またはワークフローのステップをまたぐ可能性がある場合は、独自の ClientToken を必ず指定してください。 不一致エラーと名前の衝突については provisioning-and-state.md を参照してください。

16. 安全な更新

すべての更新 API に共通するルールがあります。これを誤ると、変更する意図のなかった設定が警告なしに破棄されます。

トップレベルのメンバーを省略すると変更されません。設定ブロックを指定すると、そのブロック全体が置き換えられます。

そのため、1つのフィールドを変更するために Configuration、FilterConfiguration、または LogConfiguration を指定して更新すると、そのブロック内の他のすべてのフィールドが消去されます。 Pattern を省略して更新したイベントソースは、パターンが設定されていない状態になり、警告なしにフィルターの対象がすべてに広がります。そのため、リソースを読み取り、ブロック全体を変更し、ブロック全体を書き戻してから、もう一度読み取る必要があります。 保存された内容を確認する唯一の方法は、もう一度読み取ることだからです。

17. 一時停止、再開、再生

個別の再生 API はありません。再生とは、バスに保持されているイベントに照らして評価される、サブスクライバーの開始位置です。そのため、保持期間内にあるものは再読み込みできます。

• 作成時の StartingPosition は、LATEST（サブスクライバーの作成後に発行されたイベントのみ）または POINT_IN_TIME（保持されている履歴内の特定の時点から）です。
• 一時停止は、UpdateSubscriber の State: STOPPED で行います。バックログは保持期間の範囲内で蓄積され、再開時にバックログを配信するかスキップするかは ResumePosition で決まります。
• 再生されたイベントにはマークが付きます。 SystemMetadata."aws:DeliveryType" は LIVE ではなく REPLAY になるため、コンシューマーは再生を冪等に処理できます。
• 再生には起動時の遅延があり、その後はライブと同じ速度で実行されます。 再生が機能していないと判断する前に、遅延を考慮してください。

18. 可観測性：メトリクスとログ

このサービスの動作を把握する手段は 2 つあり、それぞれデフォルト設定が逆です。

発行メトリクスはデフォルトで有効で、名前空間は AWS/EventsV2 です。ディメンションは {EventBus} に加え、イベントソースに関連付けられたトラフィックには {EventBus, EventSource}、イングレスバイト数には {EventBus, PublisherAccount} が使われます。PublishEventsApproximateCallCount と PublishEventsApproximateSuccessCallCount を比較するのが、プロデューサーがバスに到達しているかを確認する最も手軽な方法です。**結果メトリクスが数えるのはイベントではなく呼び出しです。そのため、レスポンスを返した呼び出しは、すべてのエントリが拒否された場合でも成功としてカウントされます。イベントが到着したかどうかを示すのは、PublishEventsEntryCount と PublishEventsFailedEntriesCount の比較です。EventBus ディメンションの値はバスの ARN ではありません。**ARN を使ってクエリするとデータは返らず、トラフィックがない場合と同じように見えます。

サブスクライバーのログはデフォルトで無効であり、ログが出力されるには 2 つの設定が必要です。LogConfiguration.Level を OFF より上に設定することと、サブスクライバーをロググループに関連付ける CloudWatch Logs のベンデッドログ配信を設定することです。配信のデバッグを始める前に、両方を設定してください。observability.md に、配信の設定、メトリクス一覧、EVENT_DELIVERY_ATTEMPT レコードのフィールドが記載されています。

19. 配信の確認

発行レスポンスから分かるのは、サービスがイベントを受け付けたことです。配信されたかどうかは分かりません。イベントが到着したか確認するには、ターゲットを確認してください。

**正常な配信はすぐにターゲットへ到着するため、イベントが速やかに届かない場合は、配信中というより失敗している可能性が高いです。**ただし、リトライ期間が過ぎるまでは「何も届かなかった」と結論付けるのは適切ではありません。その間、失敗した配信はリトライされ続けるためです。

2 つのカウント上の誤りにより、正常に動作している設定が壊れているように見えることがあります。メッセージを削除せずに SQS キューを読み取ると、同じメッセージが再び読み取られるため、単純な件数は配信数を過大に示します。また、共有ターゲットには以前の実行で送信されたメッセージも蓄積されるため、実験ごとに新しいターゲットを使うか、その実行に固有のマーカーを使ってください。

20. 発行されたのに届かなかった場合

ほとんどの配信問題は、発行に成功したのにターゲットが空という同じ状態で現れます。delivery-troubleshooting.md にある**順序付きの手順に沿って作業してください。**そこでは、回答となる頻度の高い順に 11 個の原因を扱っています。

ファイルを開かずに試せる近道が 3 つあります。

• まず PublishEventsEntryCount を確認してください（第 18 章）。値が 0 なら問題はバスより上流にあり、まだ下流を確認する必要はありません。
• サブスクライバーのログを有効にしてください。 IncludePayload: FULL を指定した INFO では、リトライが尽きるのを待たずに、試行ごとのエラーと送信された正確な target_input を確認できます。
• サービスが見るイベントを確認するには、 Transformer: { Type: WITH_METADATA } を指定し、フィルターを設定せず、自分が所有するキューを指す 2 つ目のサブスクライバーを追加してもかまいません。

21. エラーとクライアントの再試行

バッチレスポンスはエントリごとです。 リクエストレベルではパブリッシュが成功していても、個々のエントリが失敗する場合があります。そのため、HTTP ステータスだけでなく、FailedEntryCount とすべてのエントリを確認してください。

不正な入力の中には、エントリ単位ではなくリクエスト全体を失敗させるものがあります。 リクエストのデシリアライズ中に検出された問題は、バッチ全体を拒否し、有効なエントリも巻き添えにします。クライアント側でエントリごとに検証し、1 つ失っても影響が小さくなるよう、バッチを小さく保ってください。

再試行可能なエラー。 ConcurrentModificationException と ThrottlingException は、バックオフを伴う再試行が可能です。InvalidInputException、AccessDeniedException、ResourceNotFoundException、IdempotentParameterMismatchException は再試行できません。リクエストを修正してください。

500 が継続する場合は、まずクライアント側のワイヤー型の問題を疑ってください。 よくある原因は、想定と異なる JSON 型の値を送信していることです。たとえば、文字列が必要な箇所に数値を送信したり、エポック秒が必要な箇所に ISO-8601 形式の文字列を送信したりするケースです。SDK は仕様に基づいて 500 を再試行しますが、不正なリクエストを再試行しても解決しないため、エスカレーションする前に型を確認してください。

22. セキュリティ、暗号化、共有、タグ付け

• 暗号化は、バスの EncryptionConfiguration.KmsKeyIdentifier で設定します。呼び出し元には、作成時にキーに対する kms:DescribeKey が必要です。また、CMK バスでは、すべてのパブリッシャーにもそのキーに対する kms:Decrypt が必要です。バスのイベントを読み戻せない呼び出し元は、イベントを書き込むことも許可されないためです。サービス側のキー ポリシーが利用できない場合、バスは StateReason: KMS_ACCESS_DENIED を伴って CREATE_FAILED になります。詳細については (security-and-sharing.md) を参照してください。
• 別のアカウントとバスを共有するには、AWS RAM を使用してください。 リソースポリシーは、AWS RAM で表現できない内容を補うための代替手段です。手書きのポリシーは AWS RAM には表示されないため、その追跡はご自身で行う必要があります。
• 一部の操作はバスの所有者に制限されています。共有リソースの取り消しなどがその例で、権限の付与だけでは不十分な場合があります。取り消しは、指定した 1 つのリソースに適用され、取り消すと元に戻せません。そのため、リソースではなくアカウントを停止するには、バスのリソースポリシーでそのアカウントに対する events:CreateSubscriber と events:CreateEventSource も拒否してください (authorization.md)。

23. コスト、クォータ、プラットフォームとの統合

設計上の判断を左右するポイントは 4 つあります。最新の料金とクォータ値は、ここではなく EventBridge の料金ページと Service Quotas で確認してください。

• 取り込みと配信のどちらも、KB 単位で切り上げて課金されます。そのため、小さなイベントが多数あると、バイト数の合計から想定されるより費用が高くなります。関連する情報を 1 つのイベントにまとめるほうが低コストです。
• 「Enriched operations」は別途課金されます。対象は JSONata の評価、スキーマのデシリアライズ、CONTENT_BASED の重複排除です。すでに冪等性キーがある場合は、DeduplicationConfiguration を設定せず、エントリごとの DeduplicationId を使用してください。
• 両方のパブリッシュ API を通じて、アカウント単位でパブリッシュがスロットリングされます。そのため、トラフィックを両方の API に分散するサービスは、1 つの予算を共有します。サブスクライバー管理には独自のアカウント単位の制限があるため、パブリッシュに余裕があっても CreateSubscriber と DeleteSubscriber がスロットリングされることがあります。ThrottlingException にはバックオフで対処してください（第 21 章）。
• CloudFormation は AWS::EventsV2:: 名前空間で新しいバスに対応しており、3 種類があります。 6 つのサブスクライバーのプロパティは作成時のみ設定可能で、置き換えは削除後に作成する方式です。そのため、テンプレート内のターゲット ARN を変更すると、その間にパブリッシュされたイベントが気づかないうちに失われる可能性があります。