翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 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)。

メタデータをストリーム内のフラグメントを埋め込むモードは 2 つあります。
+ **非永続的** – 発生したビジネス固有の基準に基づいて、ストリーム内のフラグメントに 1 回限り、またはアドホックベースでメタデータをアタッチできます。一例として、動きを検出して、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 を呼び出すと、メタデータキューからそのメタデータ項目は削除 (キャンセル) されます。