このページは Cloud Translation API によって翻訳されました。

YouTube Live Streaming API の概要

YouTube Live Streaming API を使用すると、YouTube でライブイベントを作成、更新、管理できます。また、イベント（ブロードキャスト）のスケジュール設定や、実際のブロードキャストコンテンツを表す動画ストリームとイベントとの関連付けも実行できます。

Live Streaming API は、YouTube Data API と YouTube Content ID API のコンポーネントで構成されています。Data API を使用すると、YouTube ユーザーが YouTube アカウントを管理できるようになります。また、YouTube Content ID API を使用すると、YouTube の著作権管理システムとやり取りできます。ただし、Live Streaming API を構成するすべてのリソースは、ライブイベントの作成と管理にのみ使用されます。

このドキュメントは、YouTube でライブ配信を行うためのアプリケーションを作成するデベロッパーを対象としています。このドキュメントでは、YouTube および API 自体の基本的な概念について説明します。また、API がサポートするさまざまな機能の概要についても説明します。

基本コンセプト

ブロードキャスト: ブロードキャストは、発生した時点で YouTube で視聴できるイベントを表します。イベント終了後にユーザーが視聴できるよう、ブロードキャストを YouTube 動画として録画および保存することもできます。
ストリーム: ストリームは、YouTube に通知される音声動画コンテンツを識別します。各ブロードキャストは 1 つの動画ストリームに関連付けられます。
キューポイント: キューポイントは、ライブブロードキャストに挿入できる広告ブレークを表します。

API ユースケース

アプリケーションでの API の使い方として、次のような例が挙げられます。

ブロードキャストのスケジュールを設定し、ブロードキャスト設定を定義する。ユーザーがアプリケーションを使用していくつかのブロードキャスト設定を事前に定義し、定義済みの設定を選んで特定のブロードキャストに適用できるようにすることができます。
動画ストリームとブロードキャストを関連付ける。
放送局は、（YouTube Data API を使用して）放送とその動画に関する情報を同時に定義できます。
ブロードキャスト状態（testing、live など）間の遷移を簡略化し、ユーザーがキューポイントを挿入できるようにします。

始める前に

Google API Console へのアクセス、API キーのリクエスト、アプリケーションの登録には、Google アカウントが必要です。
API リクエストを送信できるようにするため、Google にアプリケーションを登録します。
アプリケーションを登録したら、アプリケーションが使用するサービスの 1 つとして YouTube Data API を選択します。
1. API Console に移動し、登録したプロジェクトを選択します。
2. 有効な API のページにアクセスします。 API のリストで、YouTube Data API v3 のステータスと、YouTube Content Partner の場合は YouTube Content ID API のステータスがオンになっていることを確認します。
JSON（JavaScript Object Notation）データ形式のコアコンセプトについて理解しておきます。JSON は言語に依存しない一般的なデータ形式で、任意のデータ構造をシンプルなテキストで表現します。詳しくは json.org をご覧ください。

API リクエストの承認

前述のとおり、Live Streaming API では、技術的に YouTube Data API または YouTube Content ID API の一部である機能が使用されます。Content ID API を使用して、アセットのメタデータ、所有権情報、ポリシー情報を YouTube に提供できます。（アセットとは、ライブ動画ブロードキャストなどです）。また、自分の動画の申し立てや広告ポリシーの設定も行うことができます。

このセクションでは、Content ID API へのリクエストの承認要件について説明します。これは、他の Live Streaming API リクエストの承認要件とは異なります。

Data API の呼び出し: API リクエストは、ブロードキャストする YouTube チャンネルを所有する Google アカウントによって承認される必要があります。
Content ID API の呼び出し: API リクエストは、ブロードキャストする YouTube チャンネルを所有するコンテンツ所有者にリンクされている Google アカウントによって承認される必要があります。

リソースとリソースの種類

リソースとは、一意の識別子を持つ個別のデータエンティティです。次の表に、Live Streaming API を使用してやり取りするさまざまなタイプのリソースを示します。技術的には、これらのリソースはすべて、実際には YouTube Data API または YouTube Content ID API の一部として定義されます。ただし、liveBroadcast、liveStream、cuepoint リソースは、ライブイベントの作成と管理にのみ使用されます。

リソース
`liveBroadcast`	YouTube でブロードキャストしているイベントに関する情報が含まれています。`liveBroadcast` リソースは、YouTube 動画リソースを拡張し、ライブ配信に関連する動画メタデータを設定しますが、他の YouTube 動画には設定しません。したがって、`liveBroadcast` リソースは 1 つの YouTube 動画リソースに対応します。実際、`liveBroadcast` リソースと `video` リソースは同じ ID を共有します。また、Live Streaming API を使用してブロードキャストを作成した後で、YouTube Data API を使用して動画に関する追加メタデータを指定できます。
`liveStream`	YouTube に送信する動画ストリームに関する情報が含まれています。このストリームでは、YouTube ユーザーにブロードキャストされるコンテンツを提供します。作成された `liveStream` リソースは、単一の `liveBroadcast` リソースにバインドできます。（同様に、`liveBroadcast` リソースは 1 つの `liveStream` リソースにのみバインドできます。
`cuepoint`	ブロードキャスト動画ストリームにキューポイントを挿入します。これにより、広告ブレークがトリガーされる可能性があります。ブロードキャスト中にキューポイントを挿入するには、`liveBroadcasts.cuepoint` メソッドを使用します。
`video`	単一の YouTube 動画を表します。前述のように、`liveBroadcast` リソースは `video` リソースの拡張です。YouTube Data API を使用して、収録場所やブロードキャストを視聴可能な地域など、動画に関するメタデータを更新できます。
`videoAdvertisingOptions`	動画（またはブロードキャスト）の広告設定を定義します。広告オプションを設定するには、YouTube Content ID API を使用します。
`asset`	映画やテレビエピソードなどの知的財産を表します。この場合、ブロードキャスト動画がアセットです。YouTube Content ID API を使用して、`asset` リソースを作成および管理します。
`claim`	一致するアセットに動画をリンクします。ブロードキャスト動画の所有者であることを確認するために、YouTube Content ID API を使用して申し立てを作成します。
`policy`	YouTube でコンテンツを視聴できる環境、または YouTube で表示をブロックする環境を指定するルールを定義します。ブロードキャスト動画にはポリシーを適用する必要があります。また、自分のブロードキャスト動画と一致するユーザー動画に YouTube が適用するポリシーを指定することもできます。

サポートされているオペレーション

次の表は、この API がサポートするメソッドを示したものです。

運用
`list`	0 個以上のリソースのリストを取得（`GET`）します。
`insert`	新しいリソースを作成（`POST`）します。
`update`	リクエストのデータに応じて既存のリソースを変更（`PUT`）します。
`bind`	`liveBroadcast` リソースを `liveStream` リソースにリンクするか、このようなリンクを削除します。
`transition`	`liveBroadcast` リソースのステータスを変更し、新しいステータスに関連するプロセスを開始します。たとえば、ブロードキャストのステータスを `testing` に移行すると、そのブロードキャストのモニタリングストリームへの動画送信が開始されます。
`delete`	特定のリソースを削除（`DELETE`）します。

次の表は、各種リソースでサポートされている操作を示したものです。リソースの挿入、更新、または削除を実行する操作の場合は、常にユーザーによる承認が必要になります。場合によっては、list メソッドは承認済みリクエストと未承認リクエストの両方をサポートします。未承認リクエストは、パブリックデータのみを取得します。承認済みリクエストは、現在認証されているユーザーに制限された情報を取得することもできます。

サポートされている操作
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
ライブ配信

リソースのパーツ

この API ではリソースのパーツの取得が可能で、実際にこれを要求することにより、アプリケーションが不要なデータの転送、解析、保存を実行しないようにしています。このアプローチにより、API はネットワーク、CPU}、メモリの各リソースをより効率的に使用できます。

part パラメータは、YouTube Data API リソースを取得または返す API リクエストに必須パラメータです。API レスポンスに含める最上位レベル（ネストされていない）のリソースプロパティを 1 つ以上指定します。たとえば、liveStream リソースは次の部分で構成されています。

snippet
cdn
status

これらのパーツはすべて、ネストされたプロパティを含むオブジェクトであり、API サーバーが取得する（または取得しない）メタデータフィールドのグループと考えることができます。そのため、part パラメータでは、アプリケーションが実際に使用するリソースコンポーネントを選択する必要があります。この要件は次の 2 つの重要な目的を担っています。

アプリケーションが使用しないメタデータフィールドの取得に API サーバーが時間を費やすのを防ぐことで、反応時間を短縮できます。
アプリケーションが取得する不要なデータの量を低減（または排除）することで、帯域幅使用量を節減できます。

今後リソースのパーツが追加された場合でも、アプリケーションがサポートしていない新たに導入されたプロパティをリクエストすることはないため、上記の利点が損なわれることはありません。

おすすめの方法やお役立ち情報

コンテンツの申し立て

ブロードキャスト中に広告を表示する場合、イベントの開始前にブロードキャスト動画に対して申し立てを行う必要があります。コンテンツを登録するには、Content ID プログラムに参加している YouTube コンテンツパートナーである必要があります。

ライブブロードキャスト動画と通常の動画では、申し立てのプロセスが少し異なります。ライブ動画の申し立てでは、動画を作成する前に申し立てを行う必要があります。API はこれをサポートしており、ブロードキャストのライフサイクルのドキュメントで、クレームの作成を可能にする YouTube Content ID API 呼び出しについて説明しています。

コンテンツのプレビューとテスト

YouTube で受信した動画のインバウンドストリームは、次の 2 種類のアウトバウンドストリームのいずれかで動画をブロードキャストできます。

監視ストリームでは動画ブロードキャストをプレビュー（およびテスト）できます。このストリームは所有者のみがアクセスできる非公開ストリームです。ブロードキャストのモニタリングストリームが有効になっている場合にのみ、ブロードキャストを testing フェーズに移行できます。監視ストリームでは広告休憩は表示されません。
ブロードキャストストリームはユーザーが視聴可能なストリームです。ブロードキャストのプライバシーステータスは、public、private、unlisted のいずれかに設定できます。（非公開ブロードキャストは明示的に招待されたユーザーのみが視聴できるのに対して、限定公開ブロードキャストは視聴用のリンクを知っているユーザーであれば誰でも視聴できます）。

ブロードキャストストリームは、監視ストリームと同時に実行されないように遅延させることができます。ブロードキャストストリームを遅延させると、ブロードキャストにキューポイントを挿入してよりきめ細かくコントロールできます。

ただしブロードキャストストリームを遅延させると、ライブのプレゼンターが視聴中のユーザーとやり取りすることが難しくなります。また、視聴者がそのブロードキャスト以外のソースからイベントに関する重要な情報を見つける可能性が高くなります。たとえば、60 秒の遅延でスポーツイベントをブロードキャストすると、視聴者はそのブロードキャストで決定的瞬間を目撃する前に、他のリアルタイムニュースソースからその情報を知ってしまう可能性があります。

監視ストリームは、ブロードキャストするコンテンツをテストする目的で有効にすることをお勧めします。また、ユーザーとのやり取りやイベントのリアルタイムブロードキャストを重視するか、それよりもキューポイントのタイミングを細かくコントロールすることを優先させるかどうかも選択する必要があります。

ブロードキャストストリーミング中にミッドロール広告を掲載する

ブロードキャスト中、キューポイントを挿入して、広告ブレークをできるだけ早く、または指定した時間に開始できます。広告ブレークにより、YouTube はブロードキャスト中にミッドロール広告を掲載できます。

ミッドロール挿入点には次の特徴があります。

事前に定義された期間があり、これは cuepoint リソースの durationSecs プロパティを使用して設定します。広告ブレークが終了すると、視聴者はライブ配信に戻ります。
広告ブレークが発生すると、キューポイントが挿入されたときにブロードキャストを視聴している視聴者に対してのみ、広告が動画プレーヤーで再生されます。視聴者がブロードキャストを再生しているページを更新したとき、またはキューポイントを挿入した後にユーザーがブロードキャストの視聴を開始したとき、広告は掲載されません。

以下のステップは、ブロードキャスト中に広告休憩を挿入するためのベストプラクティスです。

時間オフセットの設定

キューポイントを挿入する際、キューポイントをすぐに挿入するか、ブロードキャストの特定の位置に挿入するかを指定できます。オプションは、動画のブロードキャストストリームが遅延しているかどうかによって異なります。

ブロードキャストストリームが遅延しない場合は、キューポイントをすぐに挿入するか、walltimeMs プロパティを使用して特定の時間に広告ブレークを開始できます。
- 広告ブレークをすぐに開始するには、liveBroadcasts.cuepoint メソッドを呼び出します。リクエスト本文のリソースで、insertionOffsetTimeMs プロパティの値を 0 に設定するか、そのプロパティの値を指定せず、walltimeMs プロパティの値を指定しないでください。
  
  重要: 生成される広告コンテンツは視聴者に表示されません。広告コンテンツがユーザーに表示されるまでに 30 秒程度の遅延が発生する場合があります。この遅延中、配信ストリームは視聴者に表示されますが、監視ストリームではなく実際に広告コンテンツが表示されるタイミングを判断するには、配信ストリームを視聴する必要があります。
- 特定の時間に広告ブレークを開始するには、liveBroadcasts.cuepoint メソッドを呼び出し、walltimeMs プロパティを使用して目的の時間を指定します。プロパティ値は、エポックタイムスタンプを表す整数です。
ブロードキャストストリームが遅延する場合は、上記のようにキューポイントを直ちに挿入するか、上記のように時計の時刻を指定するか、時間オフセットを指定して広告ブレークの開始タイミングを指定します。タイムオフセットでは、視聴者に広告を表示するタイミングをブロードキャストで指定します。

このオフセット値は、ブロードキャストのモニタリングストリームの開始時点からミリ秒単位で測定されます。ブロードキャストにテストフェーズがある場合は、ブロードキャストが testing ステータスに遷移するとモニターストリームが開始されます。それ以外の場合は、ブロードキャストが live ステータスに移行するとモニタリングストリームが開始されます。

キューポイントを挿入する場合は、cuepoint リソースの insertionOffsetTimeMs プロパティを目的のオフセットに設定します。

時間オフセット値を計算する

オフセット値を取得するには、モニタリングストリームを再生しているプレーヤーに対して YouTube Player API の getCurrentTime 関数を呼び出します。取得した値を使用して、その時点のブロードキャストストリームにキューポイントを挿入します。

オフセット値の範囲は、次のように計算できます。

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ は、キューポイントを正確に挿入できない可能性のあるタイムオフセットの開始時点と終了時点の 5 秒間のバッファです。例:

ブロードキャストに 5 分間のテストフェーズがある。
ブロードキャストストリームは監視ストリームよりも 60 秒遅延している。
放送局は、ブロードキャストが live ステータスに遷移してから 4 分後にキューポイントを挿入します。（つまり、ブロードキャストストリームの表示開始から 3 分後に該当する）。

この場合、オフセット時間の範囲は [(485,000), (535,000)] です。

時間はミリ秒単位で指定します。この計算に使用された値は次のとおりです。

elapsed_time=540000 – liveBroadcasts.cuepoint メソッドの呼び出し時に、モニタリングストリームが 9 分（540 秒、540, 000 ミリ秒）実行されています。
broadcast_delay=60000 - ブロードキャストストリームは 60 秒（60, 000 ミリ秒）遅れます。
Δ=5000 - キューポイントを確実に挿入できない 5 秒間のバッファ。

トラブルシューティングとエラー処理

次のガイドラインは、特定の問題が発生した場合の解決方法を示したものです。各 API メソッドから返される可能性のあるエラーの一覧については、エラードキュメントも参照してください。

ブロードキャストのステータスが別のステータスに移行する場合は、その移行に関連するアクションを YouTube が完了するまで、一時的に他のステータスが割り当てられることがあります。たとえば、ブロードキャストのステータスを ready から testing に変更する liveBroadcasts.transition リクエストを送信した場合、YouTube はブロードキャストのステータスを testStarting に設定し、ステータスの変更に関連付けられた操作を完了します。これらの操作がすべて完了すると、YouTube はブロードキャストのステータスを testing に更新し、移行が完了したことを示します。

ブロードキャストが testStarting または liveStarting ステータスで停止した場合は、liveBroadcasts.delete メソッドを呼び出してブロードキャストを削除する必要があります。次に新しいブロードキャストを作成し、ライブストリームにバインドして、テストプロセスを続行します。

liveBroadcasts.transition メソッドのドキュメントに記載されているように、メソッドを呼び出す前に、ブロードキャストにバインドされているストリームの status.streamStatus プロパティの値が active であることを確認してください。