YouTube Live Streaming API 可讓您在 YouTube 建立、更新及管理現場直播。你可以使用 API 安排活動 (直播) 時間，並將活動與代表實際直播內容的影片串流建立關聯。
Live Streaming API 實際上是由 YouTube Data API 和 YouTube Content ID API 的元件組成。Data API 可讓 YouTube 使用者管理自己的 YouTube 帳戶，YouTube Content ID API 則可與 YouTube 的著作權管理系統互動。不過，組成 Live Streaming API 的所有資源都只用於建立及管理直播活動。
本文適用於想編寫應用程式，在 YouTube 進行現場直播的開發人員。並說明 YouTube 和 API 本身的基本概念。此外，這份文件也概略說明 API 支援的各種函式。
核心概念
- 廣播
- 直播代表可在 YouTube 上即時觀看的活動。廣播內容也可以錄製並儲存為 YouTube 影片，供使用者在直播結束後觀看。
- 串流次數
- 串流會識別傳送至 YouTube 的影音內容。每個廣播都與一個影片串流相關聯。
- cuepoints
- cuepoint代表可插入現場直播的廣告插播。
API 用途
以下列出幾種在應用程式中使用 API 的方式：
-
排定廣播時間並定義廣播設定。您的應用程式可讓使用者預先定義廣播設定，然後選取要套用至特定廣播的設定。
-
關聯影片串流和廣播。
-
讓直播主能同時定義直播和影片的相關資訊 (使用 YouTube Data API)。
-
簡化廣播狀態 (例如
testing或live) 之間的轉換，並讓使用者插入提示點。
事前準備
-
您需要 Google 帳戶才能存取 Google Cloud console、要求 API 金鑰及註冊應用程式。
-
向 Google 註冊應用程式，以便提交 API 要求。
-
註冊應用程式後，請選取 YouTube Data API 做為應用程式使用的其中一項服務：
- 前往 Cloud console，選取剛註冊的專案。
- 前往「已啟用的 API」頁面。 在 API 清單中，確認 YouTube Data API v3 的狀態為「啟用」。如果您是 YouTube 內容合作夥伴，也請確認 YouTube Content ID API 的狀態為「啟用」。
-
熟悉 JavaScript 物件標記法 (JSON) 資料格式的核心概念。JSON 是一種與語言無關的常用資料格式，可透過簡單的文字方式來表示任意資料結構。詳情請參閱 json.org 網站。
授權 API 要求
如上所述，Live Streaming API 使用的功能在技術上屬於 YouTube Data API 或 YouTube Content ID API。你可以使用 Content ID API，向 YouTube 提供資產的中繼資料、擁有權資訊和政策資訊。(即時影像廣播就是資產的一種)。你也可以透過 API 聲明影片擁有權，以及設定影片的廣告政策。
本節說明向 Content ID API 提出要求的授權規定，這與授權其他 Live Streaming API 要求的規定不同。
- 呼叫 Data API
- API 要求必須由擁有直播 YouTube 頻道的 Google 帳戶授權。
- 呼叫 Content ID API
- API 要求必須由 Google 帳戶授權，該帳戶須連結至擁有直播 YouTube 頻道的內容擁有者。
資源和資源類型
資源是指具有專屬 ID 的個別資料實體。下表說明您將透過 Live Streaming API 互動的不同類型資源。從技術上來說，所有這些資源實際上都是定義為 YouTube Data API 或 YouTube Content ID API 的一部分。不過，liveBroadcast、liveStream 和 cuepoint 資源僅用於建立及管理直播活動。
| 資源 | |
|---|---|
liveBroadcast |
包含你在 YouTube 上播送的活動相關資訊。liveBroadcast 資源是 YouTube 影片資源的延伸，可設定與現場直播相關，但與其他 YouTube 影片無關的影片中繼資料。因此，一個 liveBroadcast 資源會對應到一個 YouTube 影片資源。
事實上，liveBroadcast 資源和 video 資源共用相同的 ID。使用 Live Streaming API 建立直播後，您可以使用 YouTube Data API 提供影片的其他中繼資料。 |
liveStream |
包含你傳輸至 YouTube 的影片串流相關資訊。這個串流會提供要向 YouTube 使用者播送的內容。liveStream 資源建立後，只能繫結至一個 liveBroadcast 資源。同理，liveBroadcast 資源只能繫結至一個 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 對使用者上傳的相符影片套用的政策。 |
支援作業
下表列出 API 支援的不同方法：
| 作業 | |
|---|---|
list |
擷取 (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 和記憶體資源。
對於任何會擷取或傳回 YouTube Data API 資源的 API 要求，part 參數都是必要參數。這個參數會識別一或多個應納入 API 回應的頂層 (非巢狀) 資源屬性。舉例來說，liveStream 資源包含下列部分：
snippetcdnstatus
這些部分都是包含巢狀屬性的物件，您可以將這些物件視為 API 伺服器可能 (或可能不會) 擷取的中繼資料欄位群組。因此，您必須透過 part 參數選取應用程式實際使用的資源元件。這項規定有兩個重要目的：
- 這樣一來，API 伺服器就不必花時間擷取應用程式未使用的中繼資料欄位，進而縮短延遲時間。
- 減少 (或消除) 應用程式可能擷取的不必要資料量，降低頻寬用量。
隨著資源新增更多部分，這些優勢只會增加，因為應用程式不會要求其不支援的新屬性。
提示與最佳做法
聲明內容擁有權
如要在直播期間顯示廣告，請在活動開始前聲明直播影片的擁有權。如要聲明內容擁有權，你必須是參與 Content ID 計畫的 YouTube 內容合作夥伴。
聲明現場直播影片著作權的程序與一般影片不同。對即時影像提出版權聲明時，你必須在影片實際存在前建立版權聲明。API 支援這項功能，直播生命週期文件則說明瞭可建立著作權聲明的 YouTube Content ID API 呼叫。
預覽及測試內容
YouTube 收到傳入的影片串流後，會透過兩種不同的傳出串流播送影片：
-
監控串流可讓您預覽 (及測試) 影片直播。這是私人串流，只有您能存取。只有在啟用直播的監控串流時，才能將直播轉換至
testing階段。監控串流不會顯示廣告插播。 -
播送串流是觀眾看到的串流。你可以將直播的隱私狀態設為
public、private或unlisted。(私人直播只會顯示給明確受邀觀看的使用者，不公開直播則會顯示給任何知道觀看連結的使用者)。您可以選擇延遲播送串流，避免與監控串流同時播放。延遲廣播串流後，您就能更精細地控制在廣播中插入提示點的時間。
不過，延遲直播串流會導致直播主難以與觀眾互動。此外，延遲直播會增加觀眾從其他來源發現活動重要細節的可能性。舉例來說，如果你在直播體育賽事時設定 60 秒的延遲時間，觀眾可能會先從其他即時新聞來源得知賽事的關鍵時刻，然後才在直播中看到。
YouTube 建議你為直播啟用監控串流，以便測試內容。請根據你對控制插入點時間點的需求，以及與觀眾互動或提供活動即時報導的需求，選擇是否要延遲直播。
在直播期間放送片中廣告
在廣播期間，你可以插入cuepoint，表示應盡快或在指定時間開始廣播中的廣告插播。廣告插播時間點可讓 YouTube 在直播期間放送片中廣告。
廣告插播時間點具有下列特性：
-
這段時間的長度是預先定義的，您可以使用
cuepoint資源的durationSecs屬性設定。廣告插播結束後，觀眾會回到現場直播。 -
廣告插播時，只有在插入提示點時觀看直播的觀眾，才會在影片播放器中看到廣告。如果觀看者重新整理播放廣播的頁面，或是在插入提示點後開始觀看廣播，系統就不會放送廣告。
以下步驟順序是插入廣告插播的最佳做法：
設定時間偏移
插入提示點時，您可以指定立即插入，或在廣播的特定時間點插入。具體選項取決於影片的直播串流是否延遲。
-
如果直播串流沒有延遲，您可以立即插入提示點，或使用
walltimeMs屬性，在特定時間開始廣告插播。-
如要立即開始廣告插播，請呼叫
liveBroadcasts.cuepoint方法。在要求主體中的資源中，將insertionOffsetTimeMs屬性的值設為0，或不指定該屬性的值，也不指定walltimeMs屬性的值。重要事項：請注意，觀眾不會立即看到產生的廣告素材。廣告素材可能需要約 30 秒才會顯示給使用者。延遲期間，觀眾仍可觀看廣播串流，您也必須觀看廣播串流，判斷廣告內容實際顯示的時間，而非監控串流。
-
如要在特定時間開始廣告插播，請呼叫
liveBroadcasts.cuepoint方法，並使用walltimeMs屬性指定所需時間。屬性值為整數，代表 Epoch 時間戳記。
-
-
如果廣播串流延遲，您可以按照上述方式立即插入提示點、指定時鐘時間，或指定時間偏移，決定廣告插播的開始時間。時間偏移會指定直播中應向觀眾顯示廣告的時間點。
偏移值是以毫秒為單位，從廣播的監控串流開始計算。請注意，如果直播有測試階段，則監控串流會在直播轉換為
testing狀態時開始。否則，監控直播會在直播轉換為live狀態時開始。插入提示點時，請將
cuepoint資源的insertionOffsetTimeMs屬性設為所需偏移量。
計算時間偏移值
如要擷取位移值，請為播放監控串流的播放器呼叫 YouTube Player API 的 getCurrentTime 函式。使用擷取的值，在該時間點將提示點插入廣播串流。
偏移時間可能的值可透過下列範圍計算：
[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]
如果 YouTube 無法精確插入提示點，Δ 會在可能的時差開始和結束時提供五秒緩衝。例如：
- 廣播有五分鐘的測試階段。
- 直播串流會比監控串流延遲 60 秒。
- 播送者會在播送轉換為
live狀態後四分鐘插入提示點。(也就是廣播串流顯示後三分鐘)。
在這種情況下，可能的偏移時間範圍為 [(485,000), (535,000)]。
這些時間以毫秒為單位，並使用下列值計算：
elapsed_time=540000：呼叫liveBroadcasts.cuepoint方法時，監控串流已執行九分鐘 (540 秒，540000 毫秒)。broadcast_delay=60000：廣播串流延遲 60 秒，或 60, 000 毫秒。Δ=5000：無法可靠地插入提示點時，系統會提供 5 秒的緩衝時間。
疑難排解和錯誤處理
以下指南說明如何解決可能發生的特定問題。如要查看各 API 方法可能傳回的錯誤清單，請參閱「YouTube Live Streaming API - Errors」。
-
當廣播從一個狀態轉換至另一個狀態時，YouTube 可能會暫時指派其他狀態，同時完成與轉換相關的動作。舉例來說，如果您傳送
liveBroadcasts.transition要求，將直播狀態從ready變更為testing，YouTube 會將直播狀態設為testStarting，然後完成與狀態變更相關聯的操作。完成所有動作後，YouTube 會將直播狀態更新為testing，表示轉換已完成。如果直播卡在
testStarting或liveStarting狀態，請呼叫liveBroadcasts.delete方法並刪除直播。接著建立新的直播，並繫結至直播活動，然後繼續測試程序。如
liveBroadcasts.transition方法的說明文件所述，您應先確認繫結至廣播的串流status.streamStatus屬性值為active，再呼叫該方法。