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

YouTube Live Streaming API の概要

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

Live Streaming API は、実際には YouTube Data API と YouTube Content ID API のコンポーネントで構成されています。YouTube ユーザーは Data API を使用して 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 コンテンツパートナーの場合は、YouTube Content ID API のステータスを確認します。
JavaScript Object Notation（JSON）データ形式のコアコンセプトをよく理解してください。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` リソースは、あります。Live Streaming API を使用してブロードキャストを作成した後、 YouTube Data API を使用して、動画に関する追加のメタデータを提供します。
`liveStream`	YouTube に送信する動画ストリームに関する情報が含まれます。ストリームでは、YouTube ユーザーにブロードキャストされるコンテンツを提供します。作成した `liveStream` リソースは、1 つの `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` に移行すると、YouTube はそのブロードキャストのモニターストリームへの動画の送信を開始します。
`delete`	特定のリソースを削除（`DELETE`）します。

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

サポートされる操作
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

リソースのパーツ

この 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 - Δ)]

Δ は、YouTube がキューポイントを正確に挿入できない場合に、許容される時間オフセットの開始位置と終了位置に 5 秒間のバッファします。例:

ブロードキャストに 5 分間のテストフェーズがある。
ブロードキャストストリームは監視ストリームよりも 60 秒遅延している。
ブロードキャスターは、ブロードキャストが [ live のステータス。（つまり、ブロードキャストストリームの表示開始から 3 分後に該当する）。

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

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

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

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

次のガイドラインは、特定の問題が発生した場合の解決方法を示したものです。リストの場合各 API メソッドが返す可能性のあるエラーの一覧については、YouTube Live Streaming API - エラーをご覧ください。

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

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

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