# IVS Real-Time Streaming で Amazon EventBridge を使用する
Amazon EventBridge を使用して、Amazon Interactive Video Service (IVS) ストリームをモニタリングできます。
Amazon IVS は、ストリームのステータスに関する変更イベントを Amazon EventBridge に送信します。配信されたすべてのイベントが有効です。ただし、イベントはベストエフォートベースで送信されます。つまり、以下を保証するものではありません。
+ イベントが配信される – 指定されたイベントの実行 (参加者による公開など) は可能ですが、Amazon IVS は、対応するイベントを EventBridge に送信しないことがあります。Amazon IVS は、配信を中止する前に、数時間にわたりイベントの配信を試みます。
+ 配信されたイベントが指定された時間内に到着する — 数時間前のイベントを受け取ることもあります。
+ イベントが順序通りに配信される – イベントは、特に短い時間内に送信された場合、順不同になることがあります。例えば、Participant Published の前に Participant Unpublished が送信される場合があります。
イベントが欠落したり、遅延したり、順序が違ったりすることはまれですが、通知イベントの順序や存在に依存するビジネスクリティカルなプログラムを作成するときは、こうした可能性に対処しておく必要があります。
EventBridge ルールは、以下のイベントに対して作成できます。
| イベントタイプ | イベント | 配信するタイミング |
| --- | --- | --- |
| IVS コンポジションの状態変化 | 送信先障害 | 送信先への出力の試行が失敗しました (例: S3 バケットが見つからない、S3 バケットへのアクセスが拒否された、RTMP 送信先に既にストリームが存在する）。 |
| IVS コンポジションの状態変化 | 送信先の開始 | 送信先への出力が正常に開始されました。 |
| IVS コンポジションの状態変化 | 送信先の終了 | 送信先への出力が完了しました。 |
| IVS コンポジションの状態変化 | 送信先の再接続 | 送信先への出力が中断されました。再接続を試みています。 |
| IVS コンポジションの状態変化 | セッションの開始 | コンポジションセッションが作成されました。コンポジションプロセスのパイプラインが正常に初期化されると、このイベントが発生します。この時点で、コンポジションパイプラインはステージに正常にサブスクライブされメディアを受信しており、またビデオを作成できるようになりました。 |
| IVS コンポジションの状態変化 | セッションの終了 | コンポジションセッションが完了しました。 |
| IVS コンポジションの状態変化 | セッションの失敗 | ステージの削除、1 つ以上の出力の失敗、またはその他の内部エラーにより、コンポジションパイプラインが失敗しました。 |
| IVS 参加者の録画状態の変更 | Recording Start | パブリッシャーがステージに接続し、S3 に記録されています。 |
| IVS 参加者の録画状態の変更 | Recording End | パブリッシャーがステージから切断され、残りのすべてのファイルが S3 に書き込まれました。 |
| IVS 参加者の録画状態の変更 | Recording Start Failure | パブリッシャーはステージに接続しますが、エラー (S3 バケットが見つからない場合やアクセスできない場合など) により記録が開始されません。このパブリッシャーのライブストリームは録画されません。 |
| IVS 参加者の録画状態の変更 | Recording End Failure | 記録中にエラーが発生したため (S3 バケットが見つからない場合やアクセスできない場合など）、記録は失敗で終了します。一部のオブジェクトが、設定された保存場所に引き続き書き込まれることがあります。 |
| IVS Stage Update | Participant Published | 参加者がステージへの公開を開始したとき。 |
| IVS Stage Update | Participant Unpublished | 参加者がステージへの公開を停止したとき。 |
| IVS Stage Update | 参加者の公開エラー | 参加者がステージに公開しようとしましたが失敗しました。 |
| IVS Stage Update | 参加者のレプリケーション開始 | 参加者のレプリケーションが開始されます。 |
| IVS Stage Update | 参加者のレプリケーション終了 | 参加者のレプリケーションが終了します。レプリケーションは、StopParticipantReplication API オペレーションによって終了することがあります。また、パブリッシャーが公開を停止した場合や、パブリッシャーが公開を停止し、再接続ウィンドウが期限切れになった場合にも終了することがあります。 |
| IVS Stage Update | 交換済みトークン | 既存の参加者トークンは新しいトークンと交換されます。この交換により、トークン機能のアップグレードまたはダウングレード、およびトークン属性の更新が行われます。 |
## Amazon IVS の Amazon EventBridge ルールを作成する
Amazon IVS が発行したイベントをトリガーするルールを作成できます。「*Amazon EventBridge ユーザーガイド*」の「[Amazon EventBridge でルールを作成する](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)」にある手順に従います。サービスを選択する際に、**[Interactive Video Service (IVS)]** を選択します。
## 例: Composition の状態変化
**送信先の失敗**: このイベントは、送信先への出力の試行が失敗した場合 (S3 バケットが見つからなかった場合、S3 バケットへのアクセスが拒否された場合、または RTMP 送信先に対してストリームが既に存在する場合) に送信されます。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Destination Failure",
"stage_arn": "",
"id": "",
"error_code": "e.g., AccessDeniedException",
"reason": "e.g., Access denied to S3 bucket. Please verify your bucket policy"
}
}
```
次の表に、送信先障害イベントの `error_code` と `reason` 値、およびトラブルシューティングガイダンスを示します。
| error\$1code | 理由 | トラブルシューティングのガイダンス |
| --- | --- | --- |
| ResourceNotFoundException | S3 バケットが見つかりません。バケットが存在することを確認してください。 | S3 バケットが存在し、正しいリージョンにあることを確認します。 |
| AccessDeniedException | S3 バケットへのアクセスが拒否されました。バケットポリシーを確認してください。 | S3 バケットポリシーが IVS サービスに必要なアクセス許可を付与していることを確認します。 |
| ConflictException | ストリームは既に存在します | 同じ RTMP 送信先チャネルで他のブロードキャストがアクティブでないことを確認します。 |
| InternalServerException | サービス内部エラー | オペレーションを再試行する。問題が解決しない場合は、AWS サポートまでお問い合わせください。 |
**Destination Start**: このイベントは、送信先への出力が正常に開始されたときに送信されます。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Destination Start",
"stage_arn": "",
"id": "",
}
}
```
**Destination End**: このイベントは、送信先への出力が完了したときに送信されます。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Destination End",
"stage_arn": "",
"id": "",
}
}
```
**Destination Reconnecting**: このイベントは、送信先への出力が中断され、再接続が試行中である場合に送信されます。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Destination Reconnecting",
"stage_arn": "",
"id": "",
}
}
```
**Session Start**: このイベントは、コンポジションセッションが作成されたときに送信されます。コンポジションプロセスのパイプラインが正常に初期化されると、このイベントが発生します。この時点で、コンポジションパイプラインはステージに正常にサブスクライブされメディアを受信しており、またビデオを作成できるようになりました。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Session Start",
"stage_arn": ""
}
}
```
**Session End**: このイベントは、コンポジションセッションが完了し、すべてのリソースが削除されたときに送信されます。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Session End",
"stage_arn": ""
}
}
```
**セッションの失敗**: このイベントは、ステージの削除、1 つ以上の出力の失敗、またはその他の内部エラーが原因でコンポジションパイプラインが失敗したときに送信されます。
```
{
"version": "0",
"id": "01234567-0123-0123-0123-012345678901",
"detail-type": "IVS Composition State Change",
"source": "aws.ivs",
"account": "aws_account_id",
"time": "2017-06-12T10:23:43Z",
"region": "us-east-1",
"resources": [
"arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012"
],
"detail": {
"event_name": "Session Failure",
"stage_arn": "",
"error_code": "e.g., DestinationFailure",
"reason": "e.g. One or more outputs failed"
}
}
```
次の表に、セッション障害イベントの `error_code` と `reason` 値、およびトラブルシューティングガイダンスを示します。
| error\$1code | 理由 | トラブルシューティングのガイダンス |
| --- | --- | --- |
| StageDeleted | ステージが削除されました | コンポジションを開始する前に、ステージが存在することを確認します。 |
| DestinationFailure | 1 つ以上の出力が失敗しました | 個々の送信先エラーを確認します。 |
| InternalServerException | サービス内部エラー | オペレーションを再試行する。問題が解決しない場合は、AWS サポートまでお問い合わせください。 |
## 例: 個々の参加者の録画状態の変更
**Recording Start**: このイベントは、パブリッシャーがステージに接続し、S3 に記録されているときに送信されます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Participant Recording State Change",
"source": "aws.ivs",
"account": "123456789012",
"time": "2024-03-13T22:09:58Z",
"region": "us-east-1",
"resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Recording Start",
"participant_id": "xYz1c2d3e4f",
"recording_s3_bucket_name": "bucket-name",
"recording_s3_key_prefix": "///2024-01-01T12-00-55Z"
}
}
```
**Recording End**: このイベントは、パブリッシャーがステージから切断され、残りのすべてのファイルが S3 に書き込まれたときに送信されます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Participant Recording State Change",
"source": "aws.ivs",
"account": "123456789012",
"time": "2024-03-13T22:19:04Z",
"region": "us-east-1",
"resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Recording End",
"participant_id": "xYz1c2d3e4f",
"recording_s3_bucket_name": "bucket-name",
"recording_s3_key_prefix": "///2024-01-01T12-00-55Z",
"recording_duration_ms": 547327
}
}
```
**記録開始の失敗**: このイベントは、パブリッシャーはステージに接続しましたが、エラー (S3 バケットが存在しない、または正しいリージョンにないなど) により、録画の開始に失敗しました。パブリッシャーのライブストリームは録画されません。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Participant Recording State Change",
"source": "aws.ivs",
"account": "123456789012",
"time": "2024-03-13T22:09:58Z",
"region": "us-east-1",
"resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Recording Start Failure",
"participant_id": "xYz1c2d3e4f",
"recording_s3_bucket_name": "bucket-name",
"recording_s3_key_prefix": "///2024-01-01T12-00-55Z",
"error_code": "e.g., AccessDeniedException",
"reason": "e.g., Access denied to S3 bucket. Please verify your bucket policy"
}
}
```
次の表に、記録開始の失敗イベントの `error_code` と `reason` 値、およびトラブルシューティングガイダンスを示します。
| error\$1code | 理由 | トラブルシューティングのガイダンス |
| --- | --- | --- |
| ResourceNotFoundException | S3 バケットが見つかりません。バケットが存在することを確認してください。 | S3 バケットが存在し、正しいリージョンにあることを確認します。 |
| AccessDeniedException | S3 バケットへのアクセスが拒否されました。バケットポリシーを確認してください。 | S3 バケットポリシーが IVS サービスに必要なアクセス許可を付与していることを確認します。 |
| ValidationException | ビデオコーデックは録画ではサポートされていません | パブリッシャーがサポートされているビデオコーデックを使用していることを確認します。 |
| InternalServerException | サービス内部エラー | オペレーションを再試行する。問題が解決しない場合は、AWS サポートまでお問い合わせください。 |
**記録終了の失敗**: このイベントは、録画中に発生したエラー (S3 バケットが見つからない場合やアクセスできない場合など) により、録画が失敗して終了したときに送信されます。一部のオブジェクトが、設定された保存場所に引き続き書き込まれることがあります。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Participant Recording State Change",
"source": "aws.ivs",
"account": "123456789012",
"time": "2024-03-13T22:19:04Z",
"region": "us-east-1",
"resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Recording End Failure",
"participant_id": "xYz1c2d3e4f",
"recording_s3_bucket_name": "bucket-name",
"recording_s3_key_prefix": "///2024-01-01T12-00-55Z",
"recording_duration_ms": 547327,
"error_code": "e.g., AccessDeniedException",
"reason": "e.g., Access denied to S3 bucket. Please verify your bucket policy"
}
}
```
次の表に、記録終了の失敗イベントの `error_code` と `reason` 値、およびトラブルシューティングガイダンスを示します。
| error\$1code | 理由 | トラブルシューティングのガイダンス |
| --- | --- | --- |
| ResourceNotFoundException | S3 バケットが見つかりません。バケットが存在することを確認してください。 | S3 バケットが存在し、正しいリージョンにあることを確認します。 |
| AccessDeniedException | S3 バケットへのアクセスが拒否されました。バケットポリシーを確認してください。 | S3 バケットポリシーが IVS サービスに必要なアクセス許可を付与していることを確認します。 |
| InternalServerException | サービス内部エラー | オペレーションを再試行する。問題が解決しない場合は、AWS サポートまでお問い合わせください。 |
個々の参加者の記録マージが有効で、ステージパブリッシャーがステージから切断してから再接続した場合、IVS は前のセッションと同じ S3 プレフィックスに記録しようとすることに注意してください。その結果、上記の例では `recording_s3_key_prefix` の `session_id` コンポーネントは `detail` で `session_id` フィールドとは異なる値を持つことができます。「[フラグメント化された個々の参加者の記録をマージする](rt-individual-participant-recording.md#ind-part-rec-merge-frag)」を参照してください。
## 例: Stage Update
このイベントには、イベント名 (イベントを分類する) とイベントに関するメタデータが含まれます。メタデータには、イベントをトリガーした参加者 ID、関連するステージ ID とセッション ID、ユーザー ID が含まれます。
**Participant Published**: このイベントは、参加者がステージへの公開を開始したときに送信されます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Stage Update",
"source": "aws.ivs",
"account": "123456789012",
"time": "2020-06-23T20:12:36Z",
"region": "us-west-2",
"resources": [
"arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Participant Published",
"event_time": "2025-11-18T16:40:32Z",
"user_id": "Your User Id",
"participant_id": "xYz1c2d3e4f",
"replica": true,
"source_stage_arn": "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij",
"source_session_id": "st-sdfdfdfgdfgh"
}
}
```
**Participant Unpublished**: このイベントは、参加者がステージへの公開を停止したときに送信されます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Stage Update",
"source": "aws.ivs",
"account": "123456789012",
"time": "2020-06-23T20:12:36Z",
"region": "us-west-2",
"resources": [
"arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Participant Unpublished",
"event_time": "2025-11-18T16:40:32Z",
"user_id": "Your User Id",
"participant_id": "xYz1c2d3e4f",
"replica": true,
"source_stage_arn": "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij",
"source_session_id": "st-sdfdfdfgdfgh"
}
}
```
**Participant Publish Error**: このイベントは、参加者がステージへの公開の試行に失敗したときに送信されます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Stage Update",
"source": "aws.ivs",
"account": "123456789012",
"time": "2020-06-23T20:12:36Z",
"region": "us-west-2",
"resources": [
"arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Participant Publish Error",
"event_time": "2024-08-13T14:38:17.089061676Z",
"user_id": "Your User Id",
"participant_id": "xYz1c2d3e4f",
"error_code": "BITRATE_EXCEEDED",
"replica": true,
"source_stage_arn": "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij",
"source_session_id": "st-sdfdfdfgdfgh"
}
}
```
**参加者のレプリケーション開始**: このイベントは、参加者のレプリケーションが開始されたときに送信されます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Stage Update",
"source": "aws.ivs",
"account": "123456789012",
"time": "2020-06-23T20:12:36Z",
"region": "us-west-2",
"resources": [
"arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Participant Replication Start",
"event_time": "2025-11-18T16:40:32Z",
"user_id": "Your User Id",
"participant_id": "xYz1c2d3e4f",
"destination_stage_arn": "arn:aws:ivs:us-west-2:123456789012:stage/XYZdef1G2hij",
"destination_session_id": "aBC1c2d3e4f"
}
}
```
**参加者のレプリケーション終了**: このイベントは、参加者のレプリケーションが終了したときに送信されます。レプリケーションは、StopParticipantReplication API オペレーションによって終了することがあります。また、パブリッシャーが公開を停止した場合や、パブリッシャーが公開を停止し、再接続ウィンドウが期限切れになった場合にも終了することがあります。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Stage Update",
"source": "aws.ivs",
"account": "123456789012",
"time": "2020-06-23T20:12:36Z",
"region": "us-west-2",
"resources": [
"arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Participant Replication End",
"event_time": "2025-11-18T16:40:32Z",
"user_id": "Your User Id",
"participant_id": "xYz1c2d3e4f",
"destination_stage_arn": "arn:aws:ivs:us-west-2:123456789012:stage/XYZdef1G2hij",
"destination_session_id": "aBC1c2d3e4f"
}
}
```
**トークン交換済み**: このイベントは、既存の参加者トークンが新しい参加者トークンと交換されたときに送信され、トークン機能のアップグレードまたはダウングレードおよびトークン属性の更新が行われます。
```
{
"version": "0",
"id": "12345678-1a23-4567-a1bc-1a2b34567890",
"detail-type": "IVS Stage Update",
"source": "aws.ivs",
"account": "123456789012",
"time": "2020-06-23T20:12:36Z",
"region": "us-west-2"
"resources": [
"arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij"
],
"detail": {
"session_id": "st-ZyXwvu1T2s",
"event_name": "Token Exchanged",
"event_time": "2025-11-12T20:54:53Z",
"user_id": "UpdatedUser",
"participant_id": "xYz1c2d3e4f",
"previous_token": {
"capabilities": ["SUBSCRIBE"],
"attributes": {
"role": "viewer"
},
"user_id": "InitialUser",
"expiration_time": "2025-11-12T21:54:52Z"
},
"new_token": {
"capabilities": ["SUBSCRIBE", "PUBLISH"],
"attributes": {
"role": "moderator"
},
"user_id": "UpdatedUser",
"expiration_time": "2025-11-12T22:54:52Z"
}
}
}
```