Live Snapshot

Live Snapshot API は、ライブストリームから静止画を取得し、Object Storage バケットに保存します。サムネイル、ライブプレビュー、コンテンツモデレーション用のサンプル、コンプライアンス対応のアーカイブなどに利用できます。

このガイドでは、スナップショットの動作を設定する方法、条件に一致するストリームのキャプチャを自動化する方法、オンデマンドでキャプチャセッションを開始する方法、および生成されたタスクとファイルの情報を取得する方法について説明します。

ご利用前に

• スナップショットテンプレートで使用する Object Storage の保存先とコールバックエンドポイントを準備してください。
• ルールを作成する前、またはリアルタイムキャプチャセッションを開始する前に、少なくとも1つのスナップショットパラメータテンプレートを作成してください。
• オンデマンドキャプチャの場合は、アクティブなライブストリームの配信URLを用意してください。
• タスクを照会する際は、スナップショットタスクを処理するサービスリージョン（cn、us、または sg）を使用してください。

APIの連携方法

スナップショットワークフローは、次の4つの部分で構成されます。

1. スナップショットパラメータテンプレートでは、スナップショットのキャプチャ方法と保存方法を定義します。
2. スナップショットルールでは、ライブストリームがルールに一致すると、テンプレートが自動的に適用されます。
3. リアルタイム制御では、アクティブなストリームに対するオンデマンドキャプチャセッションを開始または停止します。
4. タスククエリでスナップショットタスクを検索し、そのステータスを監視して、生成された画像ファイルの情報を返します。

テンプレートは基盤となります。スナップショットルールとリアルタイム制御のいずれにも templateId が必要なため、いずれかのワークフローを使用する前にテンプレートを作成して保存してください。

一般的なスナップショットワークフロー

1. スナップショットパラメータテンプレートを作成し、その templateId を保存します。
2. キャプチャの開始方法を選択します。
   • スナップショットルールを作成し、条件に一致する配信がライブ配信中になった際に自動的にキャプチャします。
   • StartRealTimeSnapshot を呼び出して、アクティブな配信のキャプチャをオンデマンドで開始します。
3. 各キャプチャセッションで返される persistentId を保存します。
4. QuerySnapshotTaskIds を使用して、指定した時間範囲内のタスクを検索するか、タスクの persistentId を取得します。
5. persistentId を指定して QuerySnapshotTaskDetail を使用し、タスクを監視して生成されたスナップショットファイルを確認します。
6. リアルタイムセッションを開始した後、配信終了前に終了する必要がある場合は、該当する persistentId を指定して StopRealTimeSnapshot を呼び出します。

スナップショットパラメータテンプレートの作成と管理

スナップショットパラメータテンプレートでは、サービスが画像をキャプチャして保存する方法を設定します。画像形式、サンプリング間隔、Object Storageの保存先、ファイル命名規則、およびコールバックURLを定義します。

重要: 有効なルールから参照されているテンプレートは削除できません。削除する前に、すべてのルールからテンプレートを削除してください。

ルールでスナップショットを自動化

スナップショットルールはtemplateIdをライブストリームに関連付け、該当するストリームの配信中にサービスが画像を自動的にキャプチャできるようにします。

ルールの適用対象は、具体性のレベルに応じて次の3つから指定できます：

• Domain: 指定したDomain配下のストリームに適用されます。
• アプリケーション名: 1つのアプリケーション配下のストリームに適用されます。
• ストリーム名: 特定の1つのストリームに適用されます。

システムでは最長一致ルールが使用されます。特定のストリームに一致するルールは、より広範なアプリケーションレベルのルールより優先され、アプリケーションレベルのルールはドメインレベルのルールより優先されます。デフォルトのキャプチャポリシーには広範なルールを使用し、1つのストリームに異なる設定が必要な場合は、より具体的なルールを使用してください。

重要: スナップショットをキャプチャ中のルールは削除できません。ストリームが終了するまで待つか、ルールを削除する前にキャプチャセッションを停止してください。

オンデマンドスナップショットの開始と停止

自動ルールに依存せず、アクティブなストリームから画像をキャプチャする必要がある場合は、リアルタイム制御を使用します。モデレーションイベント、ユーザーがトリガーするプレビュー、インシデントのアーカイブなどが該当します。

1. templateIdと最大5件のアクティブなストリーム配信URLを指定して、StartRealTimeSnapshotを呼び出します。
2. 各キャプチャセッションで返されるpersistentIdを保存します。
3. ライブストリームの終了に合わせてキャプチャを終了させるか、セッションのpersistentIdを指定してStopRealTimeSnapshotを呼び出し、早期に終了します。

重要: 返却されたpersistentIdはすべて保存してください。特定のリアルタイムセッションを停止し、後でタスクの詳細を取得するために必要です。

スナップショットタスクとファイルのクエリ

手動でキャプチャを開始した後、または自動キャプチャを確認する必要がある場合は、タスククエリAPIを使用してください。これらのAPIを使用すると、タスクの検索、完了 여부の確認、失敗の調査、生成された画像の特定を行えます。