本頁面由 Cloud Translation API 翻譯而成。

LiveBroadcasts: cuepoint

將提示點插入現場直播。提示點可能會觸發廣告插播。

注意：這個方法會取代 liveCuepoints.insert 方法，這個方法需要透過與 YouTube 內容擁有者相關聯的帳戶授權。這個方法的授權需求不同。

要求

HTTP 要求

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

授權

這項要求應取得至少一項範圍的授權 (進一步瞭解驗證和授權)。

範圍
`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 內容合作夥伴。內容擁有者可讓內容擁有者驗證一次參數值，並代表參數值中指定的頻道執行動作，而不必為每個管道提供驗證憑證。 `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` 其中之一。如果同時設定這兩個值，會導致錯誤。如未設定任何值，YouTube 會使用預設的 `insertionOffsetTimeMs` 時間 (`0`)，這代表系統會盡快插入提示點。
`invalidValue (400)`	`invalidInsertionOffsetTimeMs`	`cuepoint` 資源為 `insertionOffsetTimeMs` 屬性指定了無效的值。這個值必須是 `0` 或正整數。
`invalidValue (400)`	`invalidWalltimeMs`	`cuepoint` 資源為 `walltimeMs` 屬性指定了無效的值。這個值必須是代表 Epoch 紀元時間戳記的毫秒數 (以毫秒為單位)。
`backendError (5xx)`	`serviceUnavailable`	服務無法使用。請過幾分鐘後再重新提出要求。

試試看！

使用 APIs Explorer 呼叫這個 API 並查看 API 要求和回應。