LiveBroadcasts: cuepoint

在直播中插入提示點。提示點可能會觸發廣告插播。

注意：這個方法取代了 liveCuepoints.insert 方法，後者要求要求必須由與 YouTube 內容擁有者相關聯的帳戶授權。這個方法不受相同的授權要求限制。

要求

HTTP 要求

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

授權

這項要求需要至少具備下列其中一個範圍的授權。如要進一步瞭解驗證和授權，請參閱「實作 OAuth 2.0 驗證」。

範圍
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 會指派這個值，用於明確識別 cuepoint。請注意，這個值與用於識別廣播的必要 id 參數不同。傳送插入 Cue Point 的要求時，可以省略這個值。這個值會填入 API 回應中。
insertionOffsetTimeMs long
屬性值會指出應插入 cuepoint 的時間偏移量 (以毫秒為單位)。這個值會從監控串流的開頭開始計算，其預設值為 0，表示應盡快插入 cuepoint。如果直播沒有監控串流，請勿為此參數指定值。

雖然以毫秒為單位，但這個值實際上是近似值，YouTube 會盡可能在該時間插入 cuepoint。

只有在廣播串流延遲時，系統才支援這個欄位的非零值。如果廣播串流沒有延遲，0 是唯一有效的值。詳情請參閱「開始使用」一文。

注意：如果廣播活動有測試階段，系統會從測試階段開始的時間計算偏移量。

如果要求嘗試插入可為此屬性和 walltimeMs 屬性指定值的 cuepoint，API 會傳回錯誤。
walltimeMs integer
屬性值會指定應插入 cuepoint 的標準時鐘時間。這個值是整數，代表 Epoch 時間戳記 (以毫秒為單位)。

如果要求嘗試插入可為此屬性和 insertionOffsetTimeMs 屬性指定值的 cuepoint，API 會傳回錯誤。
durationSecs unsigned integer
提示點的時間長度，以秒為單位。值必須是正整數。預設值為 30。
cueType string
提示點的類型。屬性值必須設為 cueTypeAd。

回應

如果成功，這個方法會在回應內文中傳回插入的 cuepoint 資源。

錯誤

下表列出 API 在回應對此方法的呼叫時可能傳回的錯誤訊息。詳情請參閱「YouTube Live Streaming API - Errors」。

錯誤類型 錯誤詳細資料 說明
insufficientPermissions (403) insufficientLivePermissions 要求未獲授權在直播中插入提示點。
insufficientPermissions (403) liveStreamingNotEnabled 授權要求的使用者無法在 YouTube 上進行直播。如要進一步瞭解相關資訊，請參閱「開始直播」和「功能使用資格」。
rateLimitExceeded (403) userRequestsExceedRateLimit 使用者在特定時間範圍內傳送過多要求。
required (400) idRequired 必要的 id 參數必須指出要插入 cuepoint 的廣播。
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 屬性值無效。這個值必須是代表紀元時間戳記 (以毫秒為單位) 的整數。
backendError (5xx) serviceUnavailable 無法使用服務，請過幾分鐘後再嘗試提出要求。

試試看！

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