Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

LiveBroadcasts

API 現在支援將現場直播標示為「兒童專屬」，且 liveBroadcast 資源現在包含可識別現場直播「兒童專屬」狀態的屬性。《YouTube API 服務條款》和《開發人員政策》也於 2020 年 1 月 10 日更新。詳情請參閱 YouTube 直播 API 服務和 YouTube API 服務條款的修訂版本記錄。

liveBroadcast 資源代表將在 YouTube 上以即時影像串流播放的活動。

方法

這個 API 支援 liveBroadcasts 資源的下列方法：

list: 傳回符合 API 要求參數的 YouTube 廣播清單。立即試用。
插入: 建立廣播。立即試用。
更新: 更新廣播。舉例來說，您可以修改 liveBroadcast 資源的 contentDetails 物件中定義的廣播設定。立即試用。
刪除: 刪除廣播。立即試用。
繫結: 將 YouTube 廣播節目繫結至串流，或移除廣播節目與串流之間的現有繫結。一個播送只能繫結至一個視訊串流，但一個視訊串流可以繫結至多個播送。立即試用。
transition: 變更 YouTube 現場直播的狀態，並啟動與新狀態相關聯的任何程序。舉例來說，當你將廣播的狀態轉換為 testing 時，YouTube 會開始將影片傳輸至該廣播的監控串流。呼叫這個方法前，請先確認繫結至廣播的串流 status.streamStatus 屬性值為 active。立即試用。
cuepoint: 在現場直播中插入提示點。提示點可能會觸發廣告插播。

資源表示法

下列 JSON 結構顯示 liveBroadcasts 資源的格式：

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean,
    "availabilityConfig": {
      "globalConfig": {
        "excludedRegionCodes": [
          string
        ],
        "interval": {
          "startTime": datetime,
          "endTime": datetime
        }
      },
      "regionsConfig": {
        "regionIntervals": [
          {
            "regionCode": string,
            "interval": {
              "startTime": datetime,
              "endTime": datetime
            }
          }
        ]
      }
    }
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
    "adsMonetizationStatus": string,
    "eligibleForAdsMonetization": boolean,
    "cuepointSchedule": {
      "enabled": boolean,
      "pauseAdsUntil": datetime,
      "ytOptimizedCuepointConfig": string,
      "creatorCuepointConfig": {
        "scheduleStrategy": string,
        "repeatIntervalSecs": unsigned integer
      }
    }
  }
}

屬性

下表定義這個資源中顯示的屬性：

屬性
`kind`	`string` 識別 API 資源的類型。值為 `youtube#liveBroadcast`。
`etag`	`etag` 這項資源的 Etag。
`id`	`string` YouTube 指派的 ID，用於識別特定節目。
`snippet`	`object` `snippet` 物件包含活動的基本詳細資料，包括標題、說明、開始時間和結束時間。
`snippet.publishedAt`	`datetime` 播送活動新增至 YouTube 現場直播時間表的日期和時間。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`snippet.channelId`	`string` YouTube 用來識別發布直播的頻道。
`snippet.title`	`string` 廣播的標題。請注意，每場播送都代表一部 YouTube 影片。如要設定這個欄位，請修改廣播資源，或設定相應影片資源的 `title` 欄位。
`snippet.description`	`string` 廣播的說明。與 `title` 相同，您可以修改廣播資源或設定相應影片資源的 `description` 欄位，藉此設定這個欄位。
`snippet.thumbnails`	`object` 與廣播相關聯的縮圖地圖。這個物件中的每個巢狀物件，其鍵都是縮圖圖片的名稱，值則是包含縮圖其他資訊的物件。
`snippet.thumbnails.(key)`	`object` 有效鍵值如下： `default`：預設縮圖圖片。影片的預設縮圖 (或參照影片的資源，例如播放清單項目或搜尋結果) 寬 120 像素，高 90 像素。頻道的預設縮圖寬度和高度皆為 88 像素。 `medium`：縮圖圖片的更高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 320 像素，高度為 180 像素。如果是頻道，這張圖片的寬度和高度都是 240 像素。 `high`：縮圖圖片的高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 480 像素，高度為 360 像素。如果是頻道，這張圖片的寬度和高度都是 800 像素。
`snippet.thumbnails.(key).url`	`string` 圖片的網址。
`snippet.thumbnails.(key).width`	`unsigned integer` 圖片的寬度。
`snippet.thumbnails.(key).height`	`unsigned integer` 圖片的高度。
`snippet.scheduledStartTime`	`datetime` 預定開始播送的日期和時間。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。Creator Studio 支援建立廣播，不必排定開始時間。在這種情況下，只要頻道擁有者開始直播，系統就會啟動廣播。對於這類廣播，`datetime` 值對應於 Unix 紀元時間零，且無法使用 API 或在 Creator Studio 中變更。
`snippet.scheduledEndTime`	`datetime` 預計結束播送的日期和時間。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。如果 `liveBroadcast` 資源未指定這項屬性的值，系統會排定無限期繼續播放廣播。同樣地，如果未指定這項屬性的值，YouTube 會將廣播視為無限期。
`snippet.actualStartTime`	`datetime` 實際開始播送的日期和時間。只有在廣播狀態為 `live` 時，系統才會提供這項資訊。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`snippet.actualEndTime`	`datetime` 實際結束播送的日期和時間。只有在廣播狀態為 `complete` 時，系統才會提供這項資訊。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`snippet.isDefaultBroadcast`	`boolean` 這項屬性將於 2020 年 9 月 1 日當天或之後淘汰。屆時，頻道啟用直播功能後，YouTube 將停止建立預設串流和預設廣播。詳情請參閱淘汰公告。這項屬性表示這項廣播是否為預設廣播。預設廣播的運作方式啟用 YouTube 頻道的直播功能後，YouTube 會為該頻道建立預設串流和預設廣播。串流是指頻道擁有者將即時影像傳送至 YouTube 的方式，而廣播則是觀眾觀看預設串流的方式。頻道擁有者可以使用 `liveStreams.list` 和 `liveBroadcasts.list` 方法識別這些資源。頻道開始將影片串流至預設串流時，影片會顯示在頻道的預設廣播中。串流結束後，YouTube 會將完成的直播轉換為 YouTube 影片，並指派 YouTube 影片 ID。轉換完成後，影片會納入頻道的上傳影片清單。直播結束後，影片不會立即上架，延遲時間長度與直播實際長度有關。
`snippet.liveChatId`	`string` 廣播的 YouTube 直播聊天室 ID。有了這個 ID，您就能使用 `liveChatMessage` 資源的方法，擷取、插入或刪除即時通訊訊息。你也可以新增或移除聊天室管理員、禁止使用者參與聊天室，或移除現有的禁令。
`status`	`object` `status` 物件包含活動狀態的相關資訊。
`status.lifeCycleStatus`	`string` 廣播的狀態。可以使用 API 的 `liveBroadcasts.transition` 方法更新狀態。這個屬性的有效值包括： `complete`：廣播已結束。 `created`：廣播設定不完整，因此無法轉換為 `live` 或 `testing` 狀態，但已建立且有效。 `live`：廣播處於有效狀態。 `liveStarting`：廣播正在轉換為 `live` 狀態。 `ready`：廣播設定完成，廣播可以轉換為 `live` 或 `testing` 狀態。 `revoked` - 這場直播已由管理員移除。 `testStarting`：廣播正在轉換為 `testing` 狀態。 `testing` - 只有合作夥伴可以觀看廣播。
`status.privacyStatus`	`string` 廣播的隱私權狀態。請注意，廣播內容代表的正是 YouTube 影片，因此隱私權設定與影片支援的設定相同。此外，您也可以修改廣播資源或設定對應影片資源的 `privacyStatus` 欄位，藉此設定這個欄位。這個屬性的有效值如下： `private` `public` `unlisted`
`status.recordingStatus`	`string` 廣播的記錄狀態。這個屬性的有效值如下： `notRecording` `recorded` `recording`
`status.madeForKids`	`boolean` 這個值表示是否將廣播指定為針對兒童的。這個屬性值為唯讀。
`status.selfDeclaredMadeForKids`	`boolean` 在 `liveBroadcasts.insert` 要求中，頻道擁有者可使用這項屬性，將節目指定為針對兒童的。在 `liveBroadcasts.list` 要求中，只有在頻道擁有者授權 API 要求時，系統才會傳回屬性值。
`contentDetails`	`object` `contentDetails` 物件包含活動影片內容的相關資訊，例如內容是否可顯示在嵌入式影片播放器中，或是內容是否會封存，因此可在活動結束後觀看。
`contentDetails.boundStreamId`	`string` 這個值可專門識別繫結至廣播的 `live stream`。
`contentDetails.boundStreamLastUpdateTimeMs`	`datetime` `boundStreamId` 參照的直播上次更新的日期和時間。
`contentDetails.monitorStream`	`object` `monitorStream` 物件包含監控串流的相關資訊，廣播主可用來在公開顯示廣播串流前，先檢查活動內容。
`contentDetails.monitorStream.enableMonitorStream`	`boolean` 這個值會決定是否為廣播啟用監控器串流。如果啟用監控串流，YouTube 會在專屬串流中播放活動內容，僅供廣播者觀看。電視台可使用串流檢視活動內容，並找出插入提示點的最佳時間。如果您打算為直播設定 `testing` 階段，或想為活動設定直播延遲，請將這個值設為 `true`。此外，如果這項屬性的值為 `true`，則必須先將廣播轉換為 `testing` 狀態，才能轉換為 `live` 狀態。(如果屬性的值為 `false`，則廣播不得有 `testing` 階段，因此您可以將廣播直接轉換為 `live` 狀態)。如果 API 要求在 `part` 參數值中包含 `contentDetails` 部分，則必須在`update a broadcast`時設定這項屬性。不過，當您 `insert a broadcast` 時，這個屬性是選用屬性，預設值為 `true`。重要事項：一旦廣播進入 `testing` 或 `live` 狀態，就無法更新這項屬性。
`contentDetails.monitorStream.broadcastStreamDelayMs`	`unsigned integer` 如果將 `enableMonitorStream` 屬性設為 `true`，這個屬性就會決定現場直播延遲時間長度。如果 API 要求在 `part` 參數值中包含 `contentDetails` 部分，則必須在`update a broadcast`時設定這項屬性。不過，當您 `insert a broadcast` 時，這個屬性是選用屬性，預設值為 `0`。這個值表示廣播沒有直播延遲。注意：一旦廣播處於 `testing` 或 `live` 狀態，就無法更新這項屬性。
`contentDetails.monitorStream.embedHtml`	`string` HTML 程式碼，可嵌入播放監控串流的播放器。
`contentDetails.enableEmbed`	`boolean` 這項設定會指出是否可在嵌入式播放器中播放直播影片。如果選擇封存影片 (使用 `enableArchive` 屬性)，這項設定也會套用至封存的影片。如果 API 要求在 `part` 參數值中包含 `contentDetails` 部分，則必須在`update a broadcast`時設定這項屬性。不過，當您 `insert a broadcast` 時，這個屬性是選用屬性，預設值為 `true`。注意：一旦廣播處於 `testing` 或 `live` 狀態，就無法更新這項屬性。
`contentDetails.enableDvr`	`boolean` 這項設定會決定觀眾在觀看影片時，是否能使用 DVR 控制項。觀眾可使用 DVR 控制項暫停、倒轉或快轉內容，掌控影片播放體驗。此屬性的預設值為 `true`。如果 API 要求在 `part` 參數值中包含 `contentDetails` 部分，則必須在`update a broadcast`時設定這項屬性。不過，當您 `insert a broadcast` 時，這個屬性是選用屬性，預設值為 `true`。重要事項：如要讓使用者在廣播結束後立即播放內容，請務必將值設為 `true`，並將 `enableArchive` 屬性的值設為 `true`。此外，一旦廣播處於 `testing` 或 `live` 狀態，就無法更新這項屬性。
`contentDetails.recordFromStart`	`boolean` 這項設定會指出活動狀態變更為直播後，YouTube 是否會自動開始錄製廣播。這項屬性的預設值為 `true`，只有在廣播頻道允許停用直播錄製功能時，才能設為 `false`。如果頻道沒有停用錄製功能的權限，且您嘗試插入 `recordFromStart` 屬性設為 `false` 的廣播，API 會傳回 `Forbidden` 錯誤。此外，如果頻道沒有這項權限，且您嘗試更新直播，將 `recordFromStart` 屬性設為 `false`，API 會傳回 `modificationNotAllowed` 錯誤。如果 API 要求在 `part` 參數值中包含 `contentDetails` 部分，則必須在`update a broadcast`時設定這項屬性。不過，當您 `insert a broadcast` 時，這個屬性是選用屬性，預設值為 `true`。重要事項：如要讓播放內容在廣播結束後立即提供，也必須將 `enableDvr` 屬性的值設為 `true`。如果將這個屬性的值設為 `true`，但未將 `enableDvr` 屬性設為 `true`，封存的影片可能要過一天左右才能播放。注意：一旦廣播處於 `testing` 或 `live` 狀態，就無法更新這項屬性。
`contentDetails.enableClosedCaptions`	`boolean` 這項屬性已於 2015 年 12 月 17 日淘汰。請改用 `contentDetails.closedCaptionsType` 屬性。這項設定表示是否為這項廣播啟用 HTTP POST 隱藏式輔助字幕。如果 API 用戶端已使用這項資源：將屬性值設為 `true`，等同於將 `contentDetails.closedCaptionsType` 屬性設為 `closedCaptionsHttpPost`。將屬性值設為 `false`，等同於將 `contentDetails.closedCaptionsType` 屬性設為 `closedCaptionsDisabled`。
`contentDetails.closedCaptionsType`	`string` 注意：這個屬性會取代 `contentDetails.enableClosedCaptions` 屬性。這個屬性會指出廣播是否已啟用隱藏式輔助字幕，以及提供的隱藏式輔助字幕類型： `closedCaptionsDisabled`：現場直播已停用隱藏式輔助字幕。 `closedCaptionsHttpPost`：使用 HTTP POST 將字幕傳送至與直播相關聯的擷取網址。 `closedCaptionsEmbedded`：系統會使用 EIA-608 和/或 CEA-708 格式，將字幕編碼至影片串流中。
`contentDetails.projection`	`string` 這項播出的投影格式。此屬性的預設值為 `rectangular`。此屬性的有效值如下： `360` `rectangular`
`contentDetails.enableLowLatency`	`boolean` 指出是否應編碼這項廣播，以進行低延遲串流。低延遲串流可縮短廣播影片顯示給觀眾的時間，但也會影響串流觀眾的解析度。
`contentDetails.latencyPreference`	`string` 指出這場直播要使用的延遲設定。這個屬性可以取代不支援 `ultraLow` 的 `enableLowLatency`。低延遲串流可縮短影片顯示給直播觀眾的時間，但可能會影響播放流暢度。超低延遲串流可進一步縮短影片顯示給觀眾的時間，方便與觀眾互動，但超低延遲不支援隱藏式輔助字幕，也不支援高於 1080p 的解析度。這個屬性的有效值如下： `normal` `low` `ultraLow`
`contentDetails.enableAutoStart`	`boolean` 指出在繫結的 `live stream` 上開始串流影片時，是否應自動開始播放這項廣播。
`contentDetails.enableAutoStop`	`boolean` 指出頻道擁有者停止在綁定的影片串流中串流影片後，這項廣播是否應在約一分鐘後自動停止。
`contentDetails.availabilityConfig`	`object` 廣播的可用性設定。用於設定特定區域的供應情形，或封鎖特定區域。這是選用屬性，如果未設定，系統就不會強制執行。
`contentDetails.availabilityConfig.globalConfig`	`object` 廣播的全球適用性設定。影片適用於所有地區，但 `excludedRegionCodes` 清單中指定的地區除外。
`contentDetails.availabilityConfig.globalConfig.excludedRegionCodes`	`list (string)` 影片遭到封鎖的地區清單。
`contentDetails.availabilityConfig.globalConfig.interval`	`object` 影片在所有未封鎖區域的預設播放時間範圍。注意：這項屬性不支援即將播出或正在播出的直播。
`contentDetails.availabilityConfig.globalConfig.interval.startTime`	`datetime` 影片可供觀看的日期和時間。如果未指定，影片會預設為可觀看。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`contentDetails.availabilityConfig.globalConfig.interval.endTime`	`datetime` 影片停止提供的日期和時間。如果未指定，影片會永久保留。設定的開始和結束時間不得晚於五年後。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`contentDetails.availabilityConfig.regionsConfig`	`object` 廣播的區域供應情形設定。這部影片只能在指定區域觀看。
`contentDetails.availabilityConfig.regionsConfig.regionIntervals`	`list (object)` 影片可觀看的地區和時間範圍清單。如果多次指定區域，系統會使用所有間隔的聯集。
`contentDetails.availabilityConfig.regionsConfig.regionIntervals.regionCode`	`string` 影片可觀看的地區。
`contentDetails.availabilityConfig.regionsConfig.regionIntervals.interval`	`object` 影片在指定區域的觀看時間範圍。注意：這項屬性不支援即將播出或正在播出的直播。
`contentDetails.availabilityConfig.regionsConfig.regionIntervals.interval.startTime`	`datetime` 影片在指定地區上架的日期和時間。如果未指定，影片會預設為可觀看。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`contentDetails.availabilityConfig.regionsConfig.regionIntervals.interval.endTime`	`datetime` 影片在指定地區停止播映的日期和時間。如果未指定，影片會永久保留。設定的開始和結束時間不得晚於五年後。值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`statistics`	`object` `statistics` 物件包含與現場直播相關的統計資料。這些統計資料的值可能會在廣播期間變更，且只能在廣播直播時擷取。
`statistics.totalChatCount`	`unsigned long` 與廣播相關聯的即時通訊訊息總數。如果使用者可以觀看直播、直播已啟用即時通訊功能，且至少有一則訊息，系統就會顯示這項屬性和值。請注意，這項屬性在廣播結束後不會指定值。因此，這項屬性不會識別已完成現場直播的封存影片即時通訊訊息數量。
`monetizationDetails`	`object` `monetizationDetails` 物件包含串流的營利詳細資料，例如廣告自動播放器是否已開啟，或是否延後插入片中廣告。重要事項：如要為影片啟用自動廣告，頻道必須符合影片營利資格。你可以透過 API 或在 YouTube 工作室中，建立或編輯直播時設定廣播的營利設定，例如開啟營利或廣告自動化工具 (即「讓 YouTube 為你插入片中廣告」或「以固定頻率排定片中廣告」)。
`monetizationDetails.adsMonetizationStatus`	`string` 這項屬性會指出影片直播是否已啟用片中廣告。有效值為 `on` 和 `off`。
`monetizationDetails.eligibleForAdsMonetization`	`string` 這項屬性會指出影片直播是否符合片中廣告資格。直播可能因多種原因不符合資格，例如現有著作權聲明，或頻道未啟用營利功能。
`monetizationDetails.cuepointSchedule`	`object` `cuepointSchedule` 物件會指定廣播的廣告自動化設定。
`monetizationDetails.cuepointSchedule.enabled`	`boolean` 這個值會決定是否要在廣播中自動插入廣告。如果值為 `true`，YouTube 會自動在廣播中插入片中廣告。廣告放送時間表取決於 `monetizationDetails.cuepointSchedule` 物件中其他欄位的值。
`monetizationDetails.cuepointSchedule.pauseAdsUntil`	`datetime` 這個值指定 YouTube 應在指定日期和時間前，不要在廣播中插入片中廣告。值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。如要暫停廣告，這個值必須設為未來的日期時間；如要取消暫停廣告，這個欄位的值也可以設為過去的日期時間或空白值。
`monetizationDetails.cuepointSchedule.ytOptimizedCuepointConfig`	`string` 這個欄位會指定自動插入廣告提示點的選取選項。這個欄位可以指定三種模式之一： `LOW`：收益潛力較低，觀看時比較不受干擾 `MEDIUM`：收益潛力一般，兼顧觀看體驗和收益潛力 `HIGH`：收益潛力較高，觀看時較容易出現中斷
`monetizationDetails.cuepointSchedule.creatorCuepointConfig`	`object` `creatorCuepointConfig` 物件會指定廣告自動化工具選項，讓創作者選擇片中廣告的顯示方式。
`monetizationDetails.cuepointSchedule.creatorCuepointConfig.scheduleStrategy`	`string` 這個值會指定 YouTube 應遵循的提示點排程策略。有效值如下： `CONCURRENT`：所有觀眾的提示點時間相同 `NON_CONCURRENT`：系統會為不同觀眾安排不同時間的提示點。這種做法可提高廣告顯示率，讓符合資格的觀眾收到提示點。
`monetizationDetails.cuepointSchedule.creatorCuepointConfig.repeatIntervalSecs`	`unsigned integer` 這個值指定在廣播期間自動插入廣告的時間間隔 (以秒為單位)。舉例來說，如果值為 `360`，YouTube 會每隔六分鐘插入片中廣告提示點。附註：這個值指定連續提示點開始之間的時間。也就是說，間隔不是從一個提示點的結尾到下一個提示點的開頭測量，為與 YouTube 工作室設定保持一致，這個值必須是 6 分鐘的倍數，範圍從 6 分鐘到 30 分鐘。更新要求中的任何整數若在此範圍內，雖然有效，但會向下捨入至最接近的 6 分鐘倍數。

LiveBroadcasts 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

方法

資源表示法

屬性

LiveBroadcasts