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

LiveBroadcasts: cuepoint

ライブ配信にキューポイントを挿入します。キューポイントにより広告ブレークがトリガーされることがあります。

注: このメソッドは、YouTube コンテンツ所有者に関連付けられたアカウントからリクエストされる必要がある liveCuepoints.insert メソッドに代わるものです。このメソッドには、同じ承認要件はありません。

リクエスト

HTTP リクエスト

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

承認

このリクエストは、少なくとも次のうち 1 つのスコープでの承認が必要です（認証と承認の詳細をご確認ください）。

スコープ
`https://www.googleapis.com/auth/youtube`
`https://www.googleapis.com/auth/youtube.force-ssl`
`https://www.googleapis.com/auth/youtubepartner`

パラメータ

次の表に、このクエリでサポートされているパラメータを示します。このリストのパラメータはすべてクエリパラメータです。

パラメータ
必須パラメータ
`id`	`string` `id` パラメータは、キューポイントが挿入されているブロードキャストを識別します。キューポイントを挿入すると、ブロードキャストはアクティブにストリーミングされる必要があります。
オプションパラメータ
`onBehalfOfContentOwner`	`string` このパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは、さまざまな YouTube チャンネルを所有、管理している YouTube コンテンツパートナーのみを対象としています。これにより、コンテンツ所有者は、チャンネルごとに認証情報を入力しなくても、パラメータ値で指定されたチャンネルに代わって認証を一度だけ行うことができます。ユーザーが認証するアカウントを、指定した YouTube コンテンツ所有者にリンクする必要があります。 `onBehalfOfContentOwner` パラメータは、リクエストの承認認証情報が、パラメータ値で指定された YouTube コンテンツ所有者の代理として動作する YouTube ユーザーであることを示します。このパラメータは、さまざまな YouTube チャンネルを所有、管理している YouTube コンテンツパートナーを対象としています。
`onBehalfOfContentOwnerChannel`	`string` このパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは、さまざまな YouTube チャンネルを所有、管理している YouTube コンテンツパートナーのみを対象としています。これにより、コンテンツ所有者は、チャンネルごとに認証情報を提供することなく、1 回認証してパラメータ値で指定されたチャンネルに代わって操作を行うことができます。 `onBehalfOfContentOwnerChannel` パラメータは、キューポイントが挿入されるブロードキャストに関連付けられたチャンネルの YouTube チャンネル ID を指定します。このパラメータは、リクエストで `onBehalfOfContentOwner` パラメータの値を指定する場合に必須であり、このパラメータとの組み合わせでのみ使用できます。次の要件も適用されます。リクエストは、`onBehalfOfContentOwner` パラメータで指定されたコンテンツ所有者にリンクしているユーザーアカウントで承認する必要があります。 `onBehalfOfContentOwnerChannel` パラメータの値で指定するチャンネルは、`onBehalfOfContentOwner` で指定するコンテンツ所有者にリンクする必要があります。

リクエスト本文

リクエスト本文に cuepoint リソースを指定します。次の JSON 構造は、cuepoint リソースの形式を示しています。

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }

リクエスト本文の cueType フィールドは必須で、cueTypeAd に設定する必要があります。次のプロパティに値を設定することもできます。

durationSecs
insertionOffsetTimeMs（walltimeMs が設定されている場合は設定しないでください）
walltimeMs（insertionOffsetTimeMs が設定されている場合は設定しないでください）

プロパティ

次の表は、このリソースで使用されているプロパティの定義を示したものです。

プロパティ
`id`	`string` キューポイントを一意に識別するために YouTube が割り当てる値。この値は、ブロードキャストを識別する必須の `id` パラメータとは異なることに注意してください。キューポイントの挿入リクエストを送信するときは、この値を省略できます。この値は API レスポンスに入力されます。
`insertionOffsetTimeMs`	`long` このプロパティ値は、キューポイントが挿入される時間オフセットをミリ秒単位で識別します。この値はモニターストリームの先頭から測定され、デフォルト値は `0` です。これは、キューポイントができるだけ早く挿入されることを示します。ブロードキャストにモニタリングストリームがない場合は、このパラメータの値を指定しないでください。ミリ秒単位で測定されますが、実際には値は近似値であり、YouTube はその時点にできるだけ近いキューポイントを挿入します。このフィールドのゼロ以外の値は、ブロードキャストストリームが遅延されている場合にのみサポートされます。ブロードキャストストリームが遅延していない場合、有効な値は `0` のみです。詳しくは、スタートガイドをご覧ください。注: ブロードキャストにテストフェーズを設定した場合、オフセットはテストフェーズの開始時点から測定されます。このプロパティと `walltimeMs` プロパティの値を指定するキューポイントがリクエストによって挿入されると、API がエラーを返します。
`walltimeMs`	`integer` このプロパティ値は、キューポイントが挿入される実時間を指定します。この値は、エポックタイムスタンプ（ミリ秒単位）を表す整数です。このプロパティと、`insertionOffsetTimeMs` プロパティの値を指定するキューポイントをリクエストで挿入しようとすると、API はエラーを返します。
`durationSecs`	`unsigned integer` キューポイントの長さ（秒単位）。値には正の整数を指定してください。デフォルト値は `30` です。
`cueType`	`string` キューポイントのタイプ。プロパティ値は `cueTypeAd` に設定する必要があります。

レスポンス

成功すると、このメソッドはレスポンス本文に挿入された cuepoint リソースを返します。

エラー

次の表に、このメソッドを呼び出す際に API が返すエラーメッセージを示します。エラーメッセージのドキュメントには、Live Streaming API から返される可能性があるすべてのエラーが記載されています。

エラーのタイプ	エラーの詳細	説明
`insufficientPermissions (403)`	`insufficientLivePermissions`	リクエストに、ライブブロードキャストにキューポイントを挿入する権限がありません。
`insufficientPermissions (403)`	`liveStreamingNotEnabled`	リクエストを認可したユーザーに、YouTube でのライブ動画のストリーミングが有効になっていません。ユーザーは https://support.google.com/youtube/answer/2474026 と https://www.youtube.com/features で詳細を確認できます。
`rateLimitExceeded (403)`	`userRequestsExceedRateLimit`	ユーザーが一定の期間内に送信したリクエストが多すぎます。
`required (400)`	`idRequired`	必須の `id` パラメータでは、キューポイントを挿入するブロードキャストを識別する必要があります。
`required (400)`	`cueTypeRequired`	API リクエストの本文には、必須の `cueType` フィールドを指定する必要があります。
`notFound (404)`	`liveBroadcastNotFound`	`id` パラメータで指定されたブロードキャストは存在しません。
`invalidValue (400)`	`conflictingTimeFields`	`insertionOffsetTimeMs` と `walltimeMs` のいずれか 1 つのみ指定できます。両方の値を設定するとエラーになります。どちらの値も設定しない場合、YouTube はデフォルトの `insertionOffsetTimeMs` 時間（`0`）を使用します。つまり、キューポイントはできるだけ早く挿入されます。
`invalidValue (400)`	`invalidInsertionOffsetTimeMs`	`cuepoint` リソースで、`insertionOffsetTimeMs` プロパティに無効な値が指定されています。値には `0` または正の整数を指定してください。
`invalidValue (400)`	`invalidWalltimeMs`	`cuepoint` リソースで、`walltimeMs` プロパティに無効な値が指定されています。この値は、エポックタイムスタンプ（ミリ秒単位）を表す整数にする必要があります。
`backendError (5xx)`	`serviceUnavailable`	サービスを利用できません。数分後にもう一度お試しください。

実習

APIs Explorer を使用してこの API を呼び出し、API リクエストとレスポンスを確認します。