入門
Brightcove Live の冗長機能は、最初のストリームが機能しなくなった場合に Live が自動的にフェイルオーバーするバックアップストリームを作成することで、ライブイベントにおける信頼性の高いパフォーマンスを保証するのに役立ちます。
Live API へのすべてのリクエストには、次のヘッダーが必要です。
| キー | 値 | 注釈 |
|---|---|---|
X-API-KEY |
{your API Key} | Brightcove Live アカウントを開いたときにキーが提供されているはずです。 |
Content-Type |
application/json | 技術的には、content-typeヘッダーは、リクエストボディを含む書き込みリクエストにのみ必要ですが、読み取りリクエストに害を及ぼすことはありません。 |
ライブジョブの作成
冗長セットアップの場合は、2 つ以上の Brightcove ライブジョブを作成する必要があります。ジョブの唯一の要件は、同じoutput(出力)設定で作成されることです 。これを実現する最も簡単な方法は、必要な出力仕様で 1 つのジョブを作成し、copy_outputs_from_jobパラメータを使用して追加のジョブを作成することです。
これらのジョブを作成できるリージョンに制限はありませんが、お互いに比較的近くに配置することが推奨されます。
ライブジョブを作成したら、後のためにジョブ ID を保持しておいて下さい。これらのジョブを冗長グループに追加するために使用するリクエストボディは、次のようになります (以下のセクションを参照)。
[
{
"job_id": "0b76bc73f92f46dc917bbe5061c0c633"
},
{
"job_id": "0ae5a4a71dc54b3181af0f98ee407c27"
}
]
冗長グループの作成
冗長グループを作成するには、以下のPOSTリクエストを送信します。
https://api.bcovlive.io/v1/redundantgroups
リクエストボディの例を次に示します。
{
"ad_insertion": true,
"processing_regions": ["us-west-2"],
"storage_regions": ["us-west-2", "us-east-1"],
"label": "Test RG",
"live_dvr_sliding_window_duration": 1800
}
以下の表に、リクエストボディのフィールドの全リストを示します。いくつかのケースでは、これらはライブジョブの作成に使用されるフィールドと同じです。フィールドの詳細については、Live API リファレンスを参照してください。
| フィールド | タイプ | 必須/任意 | 説明 |
|---|---|---|---|
ad_insertion |
ブール値 | 任意 | このストリームで SSAI を有効にする必要がある場合は true に設定します。 |
add_cdns |
配列 | 任意 | マニフェスト生成に使用する追加の CDN プロバイダーの配列。提供された CDN ごとに、それに応じてマニフェストが先頭に付加されます。 |
drm |
オブジェクト | 任意 | まだサポートされていません。 |
encryption |
オブジェクト | 任意 | まだサポートされていません。 |
label |
文字列 | 必須 | グループを識別するためのラベル。 |
live_dvr_sliding_window_duration |
整数 | 任意 | |
notifications |
配列 | 任意 | 通知先オブジェクトまたは文字列の配列。 |
processing_regions |
配列 | 必須 | 冗長グループの処理地域。これにより、マニフェストを生成する AWS リージョンが決まります。これは、storage_regions とライブジョブが作成されるリージョンと一致することを推奨します。 |
storage_regions |
配列 | 必須 | メディアチャンクとプレイリストが S3 にアップロードされるストレージ リージョン。これは processing_regions とライブジョブが作成されるリージョンと一致することを推奨します。 |
videocloud |
オブジェクト | 任意 | Video Cloud のお客様は、ライブストリームに使用するビデオを作成するオプションがあります。 |
レスポンスは次のようになります。
{
"id": "481ff4cf0bf74956bc2ec6e126588080",
"processing_regions": [
{
"region": "us-west-2",
"probability": 1
}
],
"storage_regions": [
"us-west-2",
"us-east-1"
],
"jobs": [],
"state": "standby",
"label": "Test RG",
"live_dvr_sliding_window_duration": 1800,
"status": {
"us-west-2": null
},
"ad_insertion": true,
"outputs": {
"playback_url": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/playlist.m3u8",
"playback_url_dvr": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/playlist_dvr.m3u8",
"ssai_playback_urls": {
"26f8470f61374e608e27af9c1b3f7ff0": {
"playback_url": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/26f8470f61374e608e27af9c1b3f7ff0/playlist_ssaiM.m3u8",
"playback_url_dvr": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/26f8470f61374e608e27af9c1b3f7ff0/playlist_dvr_ssaiM.m3u8",
"description": "House Ads - 864b84f712ae40bca1510a8052b34312",
"type": "ads"
}
}
}
冗長グループの取得
GETリクエストを送信すると、すべての冗長グループを取得できます。
https://api.bcovlive.io/v1/redundantgroupsstate パラメータを使用してレスポンスをフィルタリングできます。許可される値は次のとおりです。
cancelledcancellingdeletingdisconnectedfailedfinishedfinishingprocessingstandbywaiting
page_size パラメーターもあり、1000までの整数に設定できます。デフォルトのpage_sizeは 10 です。
レスポンスは次のようになります。
{
"redundant_groups": [
{
"id": "91c268a6ec5240d79a6004f4ccf0dc6f",
"account_id": "a95ac581551b4478b27910e5675db1f8",
"user_id": "c2691d4d039040be96c190a949d754a7",
"processing_regions": [
{
"region": "us-west-2",
"probability": 1
}
],
"storage_regions": [
"us-west-2",
"us-east-1"
],
"jobs": [],
"state": "standby",
"created_at": 1594316624287,
"updated_at": 1594316624287,
"label": "Test Redundant Group",
"live_dvr_sliding_window_duration": 86400,
"status": {
"us-west-2": null
},
"outputs": {
"playback_url": "https://bcovlive-a.akamaihd.net/r91c268a6ec5240d79a6004f4ccf0dc6f/us-west-2/NA/playlist.m3u8",
"playback_url_dvr": "https://bcovlive-a.akamaihd.net/r91c268a6ec5240d79a6004f4ccf0dc6f/us-west-2/NA/playlist_dvr.m3u8"
}
},
{
"id": "279ac36e4b4d48a3abbd3e1f98cd57aa",
"account_id": "a95ac581551b4478b27910e5675db1f8",
"user_id": "c2691d4d039040be96c190a949d754a7",
"processing_regions": [
{
"region": "us-west-2",
"probability": 1
}
],
"storage_regions": [
"us-west-2",
"us-east-1"
],
"jobs": [],
"state": "standby",
"created_at": 1594323207015,
"updated_at": 1594323207015,
"label": "Test Redundant Group2",
"live_dvr_sliding_window_duration": 86400,
"status": {
"us-west-2": null
},
"outputs": {
"playback_url": "https://bcovlive-a.akamaihd.net/r279ac36e4b4d48a3abbd3e1f98cd57aa/us-west-2/NA/playlist.m3u8",
"playback_url_dvr": "https://bcovlive-a.akamaihd.net/r279ac36e4b4d48a3abbd3e1f98cd57aa/us-west-2/NA/playlist_dvr.m3u8"
}
}
]
}冗長グループにライブジョブを追加する
冗長グループを作成したら、以下の POST リクエストを送信してジョブを追加することができます。
https://api.bcovlive.io/v1/redundantgroups/{redundant_group_id}/jobs
ライブジョブ ID は、リクエスト本文で次のように指定します。
[
{
"job_id": "0b76bc73f92f46dc917bbe5061c0c633"
},
{
"job_id": "0ae5a4a71dc54b3181af0f98ee407c27"
}
]
ジョブ オブジェクトには、追加のオプション プロパティがいくつかあります。次の表は、すべてのフィールドを示しています。
| フィールド | タイプ | 必須/任意 | 説明 |
|---|---|---|---|
job_id |
文字列 | 必須 | グループに追加するジョブの ID。playlist および streams が指定されていない場合は、すべてのoutputsが使用されます。 |
playlist |
文字列 | 任意 | ストリームの出力として使用するプレイリストのラベル。もし playlist が定義されている場合、streams は 未定義でなければなりません。 |
streams |
配列 | 任意 | ストリームの出力として使用されるストリームラベルのリスト。もし streams が定義されている場合、playlist は 未定義でなければなりません。 |
このリクエストに対する成功レスポンスで、冗長グループ ID が返されます。
冗長グループのステータスの取得
冗長グループのステータスは、次の GET リクエストで取得することができます。
https://api.bcovlive.io/v1/redundantgroups/{redundant_group_id}
レスポンスは次のようになります。
{
"id": "481ff4cf0bf74956bc2ec6e126588080",
"processing_regions": [
{
"region": "us-west-2",
"probability": 1
}
],
"storage_regions": [
"us-west-2",
"us-east-1"
],
"jobs": [
{
"job_id": "0b76bc73f92f46dc917bbe5061c0c633",
"streams": [
"hls720p",
"hls540p",
"hls360p"
],
"state": "processing"
},
{
"job_id": "0ae5a4a71dc54b3181af0f98ee407c27",
"streams": [
"hls720p",
"hls540p",
"hls360p"
],
"state": "processing"
}
],
"state": "processing",
"created_at": 1568057414849,
"updated_at": 1568059153017,
"label": "Test RG",
"live_dvr_sliding_window_duration": 1800,
"status": {
"us-west-2": {
"SwitchDrift": 0,
"Ended": false,
"OnAir": "0b76bc73f92f46dc917bbe5061c0c633",
"Mode": "auto",
"InManifest": true,
"MediaSequence": 10,
"Healthiness": 0,
"Duration": 4,
"DiscontinuitySequence": 1,
"SourceChunk": {
"MediaSequence": 3639,
"Duration": 4,
"DiscontinuitySequence": 0,
"ProgramDateTime": "2019-09-09T19:59:36Z",
"LiveJobID": "0b76bc73f92f46dc917bbe5061c0c633"
},
"UpdatedAt": "2019-09-09T19:59:46Z",
"ProgramDateTime": "2019-09-09T19:59:36Z"
}
},
"ad_insertion": true,
"outputs": {
"playback_url": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/playlist.m3u8",
"playback_url_dvr": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/playlist_dvr.m3u8",
"ssai_playback_urls": {
"26f8470f61374e608e27af9c1b3f7ff0": {
"playback_url": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/26f8470f61374e608e27af9c1b3f7ff0/playlist_ssaiM.m3u8",
"playback_url_dvr": "https://playback-qa.a-live.io/r481ff4cf0bf74956bc2ec6e126588080/us-west-2/NA/26f8470f61374e608e27af9c1b3f7ff0/playlist_dvr_ssaiM.m3u8",
"description": "House Ads - 864b84f712ae40bca1510a8052b34312",
"type": "ads"
}
}
}
}
冗長グループ内の各処理リージョンは、リージョンごとにキーとなる独自の status オブジェクトを持ちます。この例では、us_west_2処理リージョンでは、on_airジョブは、0b76bc73f92f46dc917bbe5061c0c633 であることが分かります。
補足として、処理リージョンに関連する probability は、現時点では常に1になりますが、、将来の機能拡張のために、データモデルに含まれており、0と1の間の確率を持つ複数の処理リージョンが、その領域を使用する再生トラフィックのおおよその割合を示しています。
health パラメーターは、冗長化サービスによって、ジョブ間の出力処理時間を比較し、ストールが発生する前にプレーヤーが利用可能な再生バッファの秒数を推定するために使用されます。自動フェイルオーバーは、OnAirジョブのヘルスが0以下の場合に発生し、自動モードの場合、サービスは別の健全なジョブへの切り替えを試みます。
キューポイントを手動で追加する
冗長性を備えたライブ ストリームにキューポイントを手動で追加することは、通常のライブストリームにキューポイントを追加することによく似ています。冗長グループに対してこれを行うには、以下の POST リクエストを行います。
https://api.bcovlive.io/v1/redundantgroups/{redundant_group_id}/cuepoint
次のようなリクエスト本文を含めます。
{
"ad_server_data": {
"subject": "wildlife"
},
"duration": 30,
"timecode": "09:23:18:05"
}
timecodeフィールドを省略すると、キューポイントは直ちに挿入されます。
ジョブのフェイルオーバーを強制する
フェールオーバーは Brightcove Live システムによって自動的に管理されるため、ユーザーの介入は必要ありません。ただし、何らかの理由で別のジョブへのフェールオーバーを強制する場合は、on_airジョブのエンコーダを停止するのが最も簡単な方法です。
API を使用してフェイルオーバーを強制するには、以下のPUT リクエストを行います。
https://api.bcovlive.io/v1/redundantgroups/{redundant_group_id}/switch
リクエスト本文は次のようになります。
{
"mode": "manual",
"on_air": "0ae5a4a71dc54b3181af0f98ee407c27"
}
ここで、mode は manual または auto（デフォルト）のいずれかになり、on_air の値は、セカンダリジョブ ID の 1 つの値を持ちます。
注: manualモードにすると、自動ジョブフェイルオーバーは発生しません。自動フェールオーバーを再開するには、モードをauto に戻す必要があります。ボディからmodeを省略し、force クエリパラメーター?force=true をリクエストに追加することで、manualに切り替えることなく、オンエアジョブを変更できます。これにより、サービスはジョブの切り替えを強制しますが、問題が検出された場合、いつでも元に戻すことができます。
冗長ストリームを終了する
冗長ストリームを終了するには、2 つの方法があります。設計上、冗長グループは暗黙的に SEP ストリームです。冗長グループからすべてのジョブを削除することにより、冗長グループをSTANDBY モードにすることができます。
DELETEリクエストを使用してこれを行うには、次のことを行います。
https://api.bcovlive.io/v1/redundantgroups/{redundant_group_id}/jobs/{job_id}
クエリパラメータを追加する必要があります。現在on_airジョブを削除するには、?force-trueクエリパラメータを追加する必要があることに注意してください。
ストリームを終了する 2 番目の方法は、DELETE リクエストを送信して、冗長グループを完全に削除することです。
https://api.bcovlive.io/v1/redundantgroups/{redundant_group_id}
制約事項
- ライブ冗長性は、DRMで保護されたライブストリームでは、ご利用いただけません。
- Live用のトランスコードプロファイルに
h264_profile": "baseline"を使用されたライブ ジョブは冗長化でサポートされていないため、使用すると再生の停止や安定性の問題が発生する可能性があります。代わりに"h264_profile": "main"をご利用下さい。