本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 搭配 Kinesis Video Streams 使用串流中繼資料
<a name="how-meta"></a>

您可以使用 Amazon Kinesis Video Streams 生產者 SDK，在 Kinesis 影片串流中的個別片段層級內嵌中繼資料。Kinesis Video Streams 中的中繼資料是可變的鍵/值對。您可以使用它來描述片段的內容、嵌入必須與實際片段一起傳輸的相關感應器讀數，或滿足其他自訂需求。中繼資料提供為 [GetMedia](API_dataplane_GetMedia.md) 或 [GetMediaForFragmentList](API_reader_GetMediaForFragmentList.md) API 操作的一部分。它會與片段一起存放，在整個串流保留期間。您的取用應用程式可以根據中繼資料使用 來讀取、處理和反應[使用剖析器程式庫監看攝影機的輸出](parser-library.md)。

中繼資料可以用兩種模式內嵌於串流中的片段：
+ **非持久性** – 您可以根據已發生的業務特定條件，將中繼資料一次性或臨時附加至串流中的片段。例如，智慧攝影機可偵測動作，並將中繼資料新增至包含動作的對應片段，再將片段傳送至其 Kinesis 影片串流。您可以將中繼資料套用至下列格式的片段中：`Motion = true`。
+ **持久性** – 您可以根據持續的需求，將中繼資料附加至串流中的連續片段。例如，智慧攝影機會傳送與其傳送至其 Kinesis 影片串流之所有片段相關聯的目前經緯度座標。您可以將中繼資料套用至所有下列格式的片段中：`Lat = 47.608013N , Long = -122.335167W`

您可以根據應用程式的需求，同時在同一片段附加兩種模式的中繼資料。內嵌的中繼資料可能包括偵測到的物件、追蹤活動、GPS 座標等任何您欲附加至串流片段的自訂資料。中繼資料是以鍵值字串對編碼。

## 將中繼資料新增至 Kinesis 影片串流
<a name="how-meta-add"></a>

您新增至 Kinesis 影片串流的中繼資料會建模為 MKV 標籤，這些標籤會實作為鍵/值對。

中繼資料可以是*暫時性*，例如標記串流內的事件，或*持久性*，例如識別指定事件發生的片段。持久性中繼資料項目會保留，並套用至每個連續片段，直到取消為止。

**注意**  
使用 [上傳至 Kinesis Video Streams](producer-sdk.md) 新增的中繼資料項目不同於以 [TagStream](API_TagStream.md)、[UntagStream](API_UntagStream.md)、[ListTagsForStream](API_ListTagsForStream.md) 執行的串流層級標記 API。

### 串流中繼資料 API
<a name="how-meta-api"></a>

您可以在生產者 SDK 中使用下列操作來實作串流中繼資料。

**Topics**
+ [PIC](#how-meta-api-pic)
+ [C\$1\$1 生產者 SDK](#how-meta-api-cpp)
+ [Java 生產者 SDK](#how-meta-api-java)
+ [持久性和非持久性中繼資料](#how-meta-api-persistence)

#### PIC
<a name="how-meta-api-pic"></a>

```
PUBLIC_API STATUS putKinesisVideoFragmentMetadata(STREAM_HANDLE streamHandle, 
    PCHAR name, 
    PCHAR value, 
    BOOL persistent);
```

#### C\$1\$1 生產者 SDK
<a name="how-meta-api-cpp"></a>

```
/**
 * Appends a "tag" or metadata - a key/value string pair into the stream.
 */
bool putFragmentMetadata(const std::string& name, const std::string& value, bool persistent = true);
```

#### Java 生產者 SDK
<a name="how-meta-api-java"></a>

您可以使用 Java 生產者 SDK，`MediaSource`使用 將中繼資料新增至 `MediaSourceSink.onCodecPrivateData`：

```
void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String metadataValue, final boolean persistent)
throws KinesisVideoException;
```

#### 持久性和非持久性中繼資料
<a name="how-meta-api-persistence"></a>

對於非持久性中繼資料，您可以新增數個相同*​名稱*​的中繼資料項目。生產者 SDK 會收集中繼資料佇列中的中繼資料項目，直到它們在下一個片段前面。中繼資料項目套用至串流後，中繼資料佇列將清空。若要重複中繼資料，請再次呼叫 `putKinesisVideoFragmentMetadata` 或 `putFragmentMetadata`。

對於持久性中繼資料，生產者 SDK 會以與非持久性中繼資料相同的方式收集中繼資料佇列中的中繼資料項目。不過，中繼資料項目在加上下一個片段時，不會從佇列中移除。

呼叫 `putKinesisVideoFragmentMetadata`​ 或 `putFragmentMetadata`​，`persistent` 設定為 `true`，有以下行為：
+ 呼叫 API 將中繼資料項目放入佇列。佇列中的中繼資料項目將以 MKV 標籤新增至每個片段。
+ 如先前新增的中繼資料項目覆寫另一項目，請以相同*​名稱*​不同*​數值*​呼叫 API。
+ 若以空*數值*呼叫 API，將移除 (取消) 中繼資料佇列中的中繼資料項目。