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

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 要求和回應。