# 搭配 IVS 即時串流使用 Amazon EventBridge
您可以使用 Amazon EventBridge 監控您的 Amazon Interactive Video Service (IVS) 串流。
Amazon IVS 將有關串流狀態的變更事件傳送至 Amazon EventBridge。交付的所有事件都是有效的。無論如何會竭盡全力傳送事件，這表示並不能保證：
+ 事件被交付 – 可能會發生指定的事件 (例如，發布的參與者)，但 Amazon IVS 可能不會將相應的事件傳送至 EventBridge。Amazon IVS 會在放棄前嘗試用數小時交付事件。
+ 交付的事件將在指定的時間範圍內送達：您可能會收到幾個小時前的事件。
+ 按照順序交付的事件：事件可能會失序，特別是如果在短時間內傳送它們。例如，您可能會在發布參與者之前看到未發布的參與者。
雖然事件很少會遺失、遲到或失序，但如果您撰寫依賴於通知事件順序或存在的業務關鍵程式，則應該處理這些可能性。
您可以針對以下任何事件建立 EventBridge 規則。
| 事件類型 | 事件 | 傳送時機... |
| --- | --- | --- |
| IVS 合成狀態變更 | 目的地失敗 | 輸出至目的地的嘗試失敗 (例如，找不到 S3 儲存貯體、存取 S3 儲存貯體遭拒，或 RTMP 目的地已存在串流)。 |
| IVS 合成狀態變更 | 目的地啟動 | 輸出至目的地成功啟動。 |
| IVS 合成狀態變更 | 目的地結束 | 輸出至目的地完成。 |
| IVS 合成狀態變更 | 目的地重新連線 | 輸出至目的地中斷且正在嘗試重新連線。 |
| IVS 合成狀態變更 | 工作階段啟動 | 已建立合成工作階段。當合成程序管道成功初始化時，會觸發此事件。此時，合成管道已成功訂閱階段，正在接收媒體並且能夠合成視訊。 |
| IVS 合成狀態變更 | 工作階段結束 | 合成工作階段已完成。 |
| IVS 合成狀態變更 | 工作階段失敗 | 由於階段正遭刪除、一或多個輸出失敗或任何其他內部錯誤，導致合成管道失敗。 |
| IVS 參與者錄製狀態變更 | 錄製開始 | 發布者已連線至此舞台，且正在將其錄製到 S3。 |
| IVS 參與者錄製狀態變更 | 錄製結束 | 發布者已中斷與此舞台的連線，且所有剩餘的檔案都已寫入 S3。 |
| IVS 參與者錄製狀態變更 | 錄製開始失敗 | 發布者連線至階段，但由於錯誤 (例如，如果找不到或無法存取 S3 儲存貯體) 而無法開始錄製。未錄製此發布者的即時串流。 |
| IVS 參與者錄製狀態變更 | 錄製結束失敗 | 由於錄製期間遇到錯誤 (例如，如果找不到或無法存取 S3 儲存貯體)，導致錄製結束且失敗。某些物件可能仍會寫入設定的儲存位置。 |
| IVS 階段更新 | 參與者已發布 | 參與者開始發布至階段。 |
| IVS 階段更新 | 參與者未發布 | 參與者已停止發布至階段。 |
| IVS 階段更新 | 參與者發布錯誤 | 參與者嘗試發布至舞台失敗。 |
| IVS 階段更新 | 參與者複寫開始 | 有參與者複寫開始。 |
| IVS 階段更新 | 參與者複寫結束 | 有參與者複寫結束。如果發佈者已停止發佈，或者發佈者已停止發佈且重新連線時段已過期，則複寫可能會因為 StopParticipantReplication API 操作而結束。 |
| IVS 階段更新 | 已交換符記 | 現有的參與者符記會交換為新的符記。此交換會導致升級或降級的符記功能和 / 或更新的符記屬性。 |
## 為 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)**。
## 範例：合成狀態變更
**目的地失敗**：輸出至目的地的嘗試失敗 (例如，找不到 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 | reason | 疑難排解指引 |
| --- | --- | --- |
| ResourceNotFoundException | 找不到 S3 儲存貯體。請確認您的儲存貯體存在。 | 確認您的 S3 儲存貯體存在，且位於正確的區域。 |
| AccessDeniedException | 拒絕存取 S3 儲存貯體。請確認您的儲存貯體政策。 | 確認您的 S3 儲存貯體政策是否已授予 IVS 服務必要的許可。 |
| ConflictException | 串流已經存在 | 確認沒有其他廣播在相同的 RTMP 目的地頻道上處於作用中狀態。 |
| InternalServerException | 服務內部錯誤 | 重試操作。若問題仍持續發生，請聯絡 AWS Support。 |
**目的地啟動**：輸出至目的地成功啟動時，即會傳送此事件。
```
{
"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": "",
}
}
```
**目的地結束**：輸出至目的地完成時，即會傳送此事件。
```
{
"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": "",
}
}
```
**目的地重新連線**：輸出至目的地中斷且正在嘗試重新連線時，即會傳送此事件。
```
{
"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": "",
}
}
```
**工作階段啟動**：合成工作階段建立時，即會傳送此事件。當合成程序管道成功初始化時，會觸發此事件。此時，合成管道已成功訂閱階段，正在接收媒體並且能夠合成視訊。
```
{
"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": ""
}
}
```
**工作階段結束**：合成工作階段完成並刪除所有資源時，即會傳送此事件。
```
{
"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": ""
}
}
```
**工作階段失敗**：由於階段正遭刪除、一或多個輸出失敗或任何其他內部錯誤，導致合成管道失敗時，即會傳送此事件。
```
{
"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 | reason | 疑難排解指引 |
| --- | --- | --- |
| StageDeleted | 階段已遭刪除 | 在開始合成之前，請確認階段存在。 |
| DestinationFailure | 一或多個輸出失敗 | 檢查個別目的地錯誤。 |
| InternalServerException | 服務內部錯誤 | 重試操作。若問題仍持續發生，請聯絡 AWS Support。 |
## 範例：個別參與者錄製狀態變更
**錄製開始**：發布者連接至此舞台且被錄製至 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"
}
}
```
**錄製結束**：發布者中斷與此舞台的連線，且所有剩餘的檔案都已寫入 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 | reason | 疑難排解指引 |
| --- | --- | --- |
| ResourceNotFoundException | 找不到 S3 儲存貯體。請確認您的儲存貯體存在。 | 確認您的 S3 儲存貯體存在，且位於正確的區域。 |
| AccessDeniedException | 拒絕存取 S3 儲存貯體。請確認您的儲存貯體政策。 | 確認您的 S3 儲存貯體政策是否已授予 IVS 服務必要的許可。 |
| ValidationException | 影片編解碼器不支援錄製 | 確認發布者使用支援的視訊編解碼器。 |
| InternalServerException | 服務內部錯誤 | 重試操作。若問題仍持續發生，請聯絡 AWS Support。 |
**錄製結束失敗**：由於錄製期間遇到錯誤 (例如，如果找不到或無法存取 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 | reason | 疑難排解指引 |
| --- | --- | --- |
| ResourceNotFoundException | 找不到 S3 儲存貯體。請確認您的儲存貯體存在。 | 確認您的 S3 儲存貯體存在，且位於正確的區域。 |
| AccessDeniedException | 拒絕存取 S3 儲存貯體。請確認您的儲存貯體政策。 | 確認您的 S3 儲存貯體政策是否已授予 IVS 服務必要的許可。 |
| InternalServerException | 服務內部錯誤 | 重試操作。若問題仍持續發生，請聯絡 AWS Support。 |
請注意，如果啟用個別參與者錄製合併，且階段發布者中斷與階段的連線，然後重新連線，IVS 會嘗試錄製到與上一個工作階段相同的 S3 字首。因此，在上述範例中，`recording_s3_key_prefix` 的 `session_id` 元件可以具有與 `detail` 中 `session_id` 欄位不同的值。請參閱[合併分段的個別參與者錄製](rt-individual-participant-recording.md#ind-part-rec-merge-frag)。
## 範例：階段更新
階段更新事件包括事件名稱 (將事件分類) 和有關該事件的中繼資料。中繼資料包括觸發事件的參與者 ID、關聯的階段和工作階段 ID 以及使用者 ID。
**參與者已發布**：當參與者開始發布至階段時，會傳送此事件。
```
{
"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"
}
}
```
**參與者未發布**：當參與者已停止發布至階段時，會傳送此事件。
```
{
"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"
}
}
```
**參與者發布錯誤**：參與者嘗試發布至舞台失敗時，就會傳送此事件。
```
{
"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"
}
}
}
```