# 搭配 IVS 低延遲串流使用 Amazon EventBridge
<a name="eventbridge"></a>

您可以使用 Amazon EventBridge 監控您的 Amazon Interactive Video Service (IVS) 串流。

Amazon IVS 將有關串流狀態的變更事件傳送至 Amazon EventBridge。交付的所有事件都是有效的。無論如何會竭盡全力傳送事件，這表示並不能保證：
+ 事件被交付 — 可能會發生指定的事件 (例如，串流開始)，但 Amazon IVS 可能不會將相應的變更事件傳送至 EventBridge。Amazon IVS 會在放棄前嘗試用數小時交付事件。
+ 交付的事件將在指定的時間範圍內送達：您可能會收到幾個小時前的事件。
+ 按照順序交付的事件：事件可能會失序，特別是如果在短時間內傳送它們。例如，您可能會看到串流下去又上來。

雖然事件很少會遺失、遲到或失序，但如果您撰寫依賴於通知事件順序或存在的業務關鍵程式，則應該處理這些可能性。

您可以針對以下任何事件建立 EventBridge 規則。


| 事件類型 | 事件 | 傳送時機 ... | 
| --- | --- | --- | 
| IVS 串流狀態變更 | 工作階段已建立 | 已成功使用頻道串流金鑰，並已建立串流工作階段。在處理影片或將其傳送給檢視器之前，會在串流啟動時先觸發此事件。此事件可幫助您判斷串流是否已啟動但無法上線；例如，因為配置錯誤或違反限制而造成該情況。 | 
| IVS 串流狀態變更 | 工作階段已結束 | 編碼器斷開連接，Amazon IVS 無法再接收影像。此事件可幫助您判斷編碼器停止發送媒體的時間。如為多軌串流，`code` 欄位可以提供工作階段結束原因的其他詳細資訊。如需詳細資訊，請參閱 [StreamEvent](https://docs.aws.amazon.com//ivs/latest/LowLatencyAPIReference/API_StreamEvent.html) API 物件中的 `code` 欄位。<br />注意：當編碼器斷線時，可能會在「串流結束」之前先出現「工作階段已結束」事件。這是因為當 Amazon IVS 仍在處理影像時，在「工作階段已結束」事件後可能會有一段很短的時間。 | 
| IVS 串流狀態變更 | 串流開始 | 正在處理串流，觀眾可以觀看區段。此事件表示系統正在處理影片串流，並可透過檢視器觀看。此事件可幫助您判斷串流是否已成功上線。 | 
| IVS 串流狀態變更 | 串流結束 | 停止處理串流，不再為觀看者產生影像區段。此事件可幫助判定串流結束的時間，且觀看者無法消費任何新的影像區段。(另請參閱「工作階段已結束」中的說明。) | 
| IVS 串流狀態變更 | 串流失敗 | 尚未處理串流並且不可用，因為已超出處理容量。 | 
| IVS 串流狀態變更 | 串流接管 | 現有串流已受到接管。 | 
| IVS 串流狀態變更 | 串流接管失敗 | 嘗試接管現有串流遭拒。code 欄位會提供串流接管失敗原因的其他詳細資訊。以下提供多個值；請注意，IVS 主控台會提供長說明，但不會透過 IVS API 或 EventBridge 傳遞：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/ivs/latest/LowLatencyUserGuide/eventbridge.html)  | 
| IVS 串流 Health (運作狀態) 變更 | 耗盡開始 | 串流沒有接收來自實況主的資料；串流被稱為處於「耗盡」狀態。 | 
| IVS 串流 Health (運作狀態) 變更 | 耗盡結束 | 耗盡的串流開始接收來自實況主的資料，串流又恢復運作。 | 
| IVS 限制違規 | 擷取位元速率 | 傳入串流的位元速率超過 Amazon IVS 限制。 | 
| IVS 限制違規 | 擷取解析度 | 傳入串流的解析度超過 Amazon IVS 限制。 | 
| IVS 限制違規 | 並行廣播 | 同時串流的頻道總數超過 Amazon IVS 限制。 | 
| IVS 限制違規 | 並行觀眾 | 同時觀看頻道的觀眾總數超過 Amazon IVS 限制。 | 
| IVS 錄製狀態變更 | 錄製開始 | 系統開始處理串流，並建立且驗證錄製字首。系統會將區段寫入為頻道所設定的儲存位置。<br />請注意，即時串流啟動並發出「錄製開始」事件之後，需要等待一段時間才能將資訊清單檔案和影片片段寫入為頻道設定的 S3 儲存貯體。建議您只在傳送「錄製結束」事件之後播放或處理錄製的串流。 | 
| IVS 錄製狀態變更 | 錄製結束 | 此頻道的串流結束並且錄製停止。 | 
| IVS 錄製狀態變更 | 錄製開始失敗 | 串流開始，但由於錯誤，錄製無法開始 (例如，S3 儲存貯體不存在或不在正確的區域)。不會錄製此即時串流。 | 
| IVS 錄製狀態變更 | 錄製結束失敗 | 由於錄製過程中發生錯誤 (例如，嘗試寫入主播放清單失敗)，錄製以失敗結束。某些物件可能仍會寫入設定的儲存位置。 | 

**串流 ID 備註：**`stream_id` 欄位 (在許多事件中) 是每次頻道上線時指派的唯一串流識別符。對於特定頻道，每個即時串流都有一個新的 `stream_id`。因此，每個頻道 ARN 可以有許多相應的串流 ID。串流 ID 可讓客戶區分相同頻道上的不同串流工作階段。

**部分事件延遲備註：**編碼器組態設定，尤其是 IDR/關鍵影格間隔，會影響串流啟動的時間和相關事件 (串流開始和錄製開始) 的延遲。較短的關鍵影格間隔可減少此延遲。請參閱 *Amazon IVS 串流組態*中的[「減少延遲」](streaming-config.md#streaming-config-reducing-latency)，以了解有關設定 `IDR/Keyframe` 的資訊。

## 為 Amazon IVS 建立 Amazon EventBridge 規則
<a name="eventbridge-creating-rules"></a>

您可以建立針對 Amazon IVS 發出的事件而觸發的規則。遵循 *Amazon EventBridge 使用者指南*中的[在 Amazon EventBridge 中建立規則](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)的步驟。選取服務時，請選擇 **Interactive Video Service (IVS)**。

## 範例：串流狀態變更
<a name="eventbridge-examples-stream-state-change"></a>

**工作階段已建立：**當頻道串流金鑰成功使用，且串流工作階段建立時，會傳送此事件。

```
{
   "version": "0",
   "id": "aa5b7a40-36cf-8dc4-5554-32d70e047215",
   "detail-type": "IVS Stream State Change",
   "source": "aws.ivs",
   "account": "535011710559",
   "time": "2024-09-09T16:17:26Z",
   "region": "us-east-1",
   "resources": [
      "arn:aws:ivs:us-west-2:535011710559:channel/UCGaMPGLCbcE"
   ],
   "detail": {
      "event_name": "Session Created",
      "channel_name": "",
      "stream_id": "st-1AuTyMDASvHUTSb8p5PvbsO"
   }
}
```

**工作階段已結束：**當編碼器中斷連線且 IVS 不再接收視訊時，會傳送此事件。

```
{
   "version": "0",
   "id": "6f2723f3-ee31-9e48-b030-ac865e261a8e",
   "detail-type": "IVS Stream State Change",
   "source": "aws.ivs",
   "account": "535011710559",
   "time": "2024-09-09T16:17:26Z",
   "region": "us-east-1",
   "resources": [
      "arn:aws:ivs:us-west-2:535011710559:channel/UCGaMPGLCbcE"
   ],
   "detail": {
      "event_name": "Session Ended",
      "channel_name": "",
      "code": "MultitrackInputNotAllowed",
      "stream_id": "st-1AuTyMDASvHUTSb8p5PvbsO"
   }
}
```

**串流開始：**當正在處理串流且區段可供觀眾使用時，會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
     "event_name": "Stream Start",
     "channel_name": "Your Channel",
     "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

**串流結束：**當串流停止處理且不再為觀看者產生影像區段時，會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
     "event_name": "Stream End",
     "channel_name": "Your Channel",
     "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

**串流失敗：**當串流尚未處理，且因為超過處理容量而無法使用時，會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
     "event_name": "Stream Failure",
     "channel_name": "Your Channel",
     "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn",
     "reason": "Transcode capacity exceeded. Please try again."
   }
}
```

**串流接管：**當現有串流受到接管時，會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
],
   "detail": {
      "event_name": "Stream Takeover",
      "channel_name": "Your Channel",
      "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

**串流接管失敗：**當嘗試接管現有串流遭拒時，會傳送此事件。這可能是因為編解碼器/解析度/視訊軌類型不相符、優先順序整數無效，或超過每個串流的接管次數上限。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
],
   "detail": {
      "event_name": "Stream Takeover Failure",
      "channel_name": "Your Channel",
      "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn",
      "code": "StreamTakeoverInvalidPriority"
   }
}
```

## 範例：串流 Health (運作狀態) 變更
<a name="eventbridge-examples-stream-health-change"></a>

**耗盡開始：**串流沒有接收來自實況主的資料時傳送此事件；串流被稱為處於「耗盡」狀態。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream Health 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
     "event_name": "Starvation Start",
     "channel_name": "Your Channel",
     "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

**耗盡結束：**耗盡的串流開始接收來自實況主的資料時傳送此事件，並且串流又恢復運作。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Stream Health 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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
     "event_name": "Starvation End",
     "channel_name": "Your Channel",
     "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

## 範例：限制違規
<a name="eventbridge-examples-limit-breach"></a>

所有限制違規事件包括違規限制的名稱、限制的值以及超出限制的數目 (違規時的值會減去限制)。

**擷取位元速率：**當傳入串流的位元速率超過 Amazon IVS 限制時，會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Limit Breach",
   "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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
     "limit_name": "Ingest Bitrate",
     "limit_value": 1234,
     "exceeded_by": 3,
     "limit_unit": "bits per second",
     "channel_name": "Your Channel",
     "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

**擷取解析度：**當傳入串流的解析度 (總像素或每個邊緣的像素) 超過 Amazon IVS 限制時，會傳送此事件。

超過最大像素總數：

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Limit Breach",
   "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:channel/12345678-1a23-4567-a1bc-1a2b34567890"
   ],
   "detail": {
      "limit_name": "Ingest Resolution",
      "limit_value": 495000,
      "exceeded_by": 426600,
      "limit_unit": "total pixels",
      "channel_name": "Your Channel",
      "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

超過每個邊緣的最大像素數：

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Limit Breach",
   "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:channel/12345678-1a23-4567-a1bc-1a2b34567890"TBD
   ],
   "detail": {
      "limit_name": "Ingest Resolution",
      "limit_value": 855,
      "exceeded_by": 45,
      "limit_unit": "pixels per edge",
      "channel_name": "Your Channel",
      "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn"
   }
}
```

**並行廣播：**當同時串流的頻道總數超過 Amazon IVS 限制時，會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Limit Breach",
   "source": "aws.ivs",
   "account": "aws_account_id",
   "time": "2017-06-12T10:23:43Z",
   "region": "us-east-1",
   "resources": [],
   "detail": {
     "limit_name": "Concurrent Broadcasts",
     "limit_value": 2, 
     "exceeded_by": 3,
     "limit_unit": "active streams"
   }
}
```

**並行觀眾：**當同時觀看頻道的觀眾總數超過 Amazon IVS 限制時，就會傳送此事件。

```
{
   "version": "0",
   "id": "01234567-0123-0123-0123-012345678901",
   "detail-type": "IVS Limit Breach",
   "source": "aws.ivs",
   "account": "aws_account_id",
   "time": "2017-06-12T10:23:43Z",
   "region": "us-east-1",
   "resources": [],
   "detail": {
     "limit_name": "Concurrent Viewers",
     "limit_value": 10,
     "exceeded_by": 11,
     "limit_unit": "viewers"
   }
}
```

## 範例：錄製狀態變更
<a name="eventbridge-examples-recording-state-change"></a>

對於所有錄製狀態變更事件，儲存此即時串流之所有物件的最上層路徑為 `recording_s3_key_prefix`。如果發生故障，失敗原因在 `recording_status_reason` 中。`recording_duration_ms` 欄位是錄製持續時間的毫秒數。

**錄製開始：**開始處理串流並將區段寫入為頻道設定的儲存位置時會傳送此事件。

```
{
    "version": "0",
    "id": "12345678-1a23-4567-a1bc-1a2b34567890",
    "detail-type": "IVS Recording State Change",
    "source": "aws.ivs",
    "account": "123456789012",
    "time": "2020-06-23T20:12:36Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ivs:us-west-2:123456789012:channel/AbCdef1G2hij"
    ],
    "detail": {
        "channel_name": "Your Channel",
        "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn",
        "recording_status": "Recording Start",
        "recording_status_reason": "",
        "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings",
        "recording_s3_key_prefix": "ivs/v1/123456789012/AbCdef1G2hij/2020/6/23/20/12/j8Z9O91ndcVs",
        "recording_duration_ms": 0,
        "recording_session_id": "a6RfV23ES97iyfoQ"
    }
}
```

**錄製結束：**此頻道的串流結束並且錄製停止時會傳送此事件。

```
{
    "version": "0",
    "id": "12345678-1a23-4567-a1bc-1a2b34567890",
    "detail-type": "IVS Recording State Change",
    "source": "aws.ivs",
    "account": "123456789012",
    "time": "2020-06-24T07:51:32Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ivs:us-west-2:123456789012:channel/AbCdef1G2hij"
    ],
    "detail": {
        "channel_name": "Your Channel",
        "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn",
        "recording_status": "Recording End",
        "recording_status_reason": "",
        "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings",
        "recording_s3_key_prefix": "ivs/v1/123456789012/AbCdef1G2hij/2020/6/23/20/12/j8Z9O91ndcVs",
        "recording_duration_ms": 99370264,
        "recording_session_id": "a6RfV23ES97iyfoQ",
        "recording_session_stream_ids": ["st-254sopYUvi6F78ghpO9vn0A", "st-1A2b3c4D5e6F78ghij9Klmn"]
    }
}
```

**錄製開始失敗：**當串流開始，但由於錯誤，錄製無法開始 (例如，S3 儲存貯體不存在或不在正確的區域) 時會傳送此事件。不會錄製此即時串流。

```
{
    "version": "0",
    "id": "12345678-1a23-4567-a1bc-1a2b34567890",
    "detail-type": "IVS Recording State Change",
    "source": "aws.ivs",
    "account": "123456789012",
    "time": "2020-06-23T20:12:36Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ivs:us-west-2:123456789012:channel/AbCdef1G2hij"
    ],
    "detail": {
        "channel_name": "Your Channel",
        "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn",
        "recording_status": "Recording Start Failure",
        "recording_status_reason": "ValidationException",
        "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings",
        "recording_s3_key_prefix": "",
        "recording_duration_ms": 0,
        "recording_session_id": "a6RfV23ES97iyfoQ"
    }
}
```

**錄製結束失敗：**由於錄製過程中發生錯誤，錄製結束時失敗，此時會傳送此事件。某些物件可能仍會寫入設定的儲存位置。

```
{
    "version": "0",
    "id": "12345678-1a23-4567-a1bc-1a2b34567890",
    "detail-type": "IVS Recording State Change",
    "source": "aws.ivs",
    "account": "123456789012",
    "time": "2020-06-24T07:51:32Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ivs:us-west-2:123456a7-ab1c-2d34-e5f6-1a2b3c4d5678"
    ],
    "detail": {
        "channel_name": "Your Channel",
        "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn",
        "recording_status": "Recording End Failure",
        "recording_status_reason": "InternalServerException",
        "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings",
        "recording_s3_key_prefix": "ivs/v1/123456789012/AbCdef1G2hij/2020/6/23/20/12/j8Z9O91ndcVs",
        "recording_duration_ms": 0,
        "recording_session_id": "a6RfV23ES97iyfoQ"
    }
}
```