入門
Brightcove Live の冗長性機能は、最初のストリームが機能しなくなった場合に Live が自動的にフェイルオーバーするバックアップストリームを作成することで、ライブイベントの信頼性の高いパフォーマンスを保証するのに役立ちます。
Live API へのすべてのリクエストには、次のヘッダーが必要です。
キー | 値 | 注 |
---|---|---|
X-API-KEY |
{your API Key} | Brightcove Live アカウントを開いたときにキーが提供されているはずです |
Content-Type |
アプリケーション/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/redundantgroups
state
パラメータを使用して応答をフィルタリングできます。許可される値は次のとおりです。
cancelled
cancelling
deleting
disconnected
failed
finished
finishing
processing
standby
waiting
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
、将来の機能強化のために、データモデルに含まれています。これにより、確率を持つ複数の処理領域が可能になりますは、そのリージョンを使用する再生トラフィックのおおよその割合を表します。
キューポイントを手動で追加する
冗長性を備えたライブストリームにキューポイントを手動で追加することは、通常のライブストリームにキューポイントを追加することと非常によく似ています。冗長グループに対してこれを行うには、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
モードをに戻す必要があります 。ボディからモードを省略し、force query ?force=true
パラメータを要求に追加することで、手動に切り替えることなく、オンエアジョブを変更できます。これにより、サービスはジョブの切り替えを強制しますが、問題が検出された場合、いつでも元に戻す可能性があります。
冗長ストリームを終了する
冗長ストリームを終了するには、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で保護されたライブストリームで使用できます。