LiveBroadcasts: list

傳回符合 API 要求參數的 YouTube 廣播訊息清單。

常見用途

要求

HTTP 要求

GET https://www.googleapis.com/youtube/v3/liveBroadcasts

授權

這項要求至少需要取得下列其中一個範圍的授權 (進一步瞭解驗證和授權)。

範圍
https://www.googleapis.com/auth/youtube.readonly
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl

參數

下表列出這項查詢支援的參數。這裡列出的所有參數都是查詢參數。

參數
必要參數
part string
part 參數會指定一份以半形逗號分隔的清單，其中包含 API 回應要納入的一或多個 liveBroadcast 資源屬性。可納入參數值的 part 名稱包括 id、snippet、contentDetails、monetizationDetails 和 status。
篩選器 (明確指定下列其中一個參數)
broadcastStatus string
broadcastStatus 參數會篩選 API 回應，只納入具有指定狀態的廣播訊息。

可接受的值如下：
  • active - 傳回目前的現場直播。
  • all - 傳回所有廣播。
  • completed - 傳回已結束的廣播。
  • upcoming - 傳回尚未開始的廣播。
id string
id 參數會指定一份以半形逗號分隔的 YouTube 廣播 ID 清單，用來識別要擷取的廣播訊息。在 liveBroadcast 資源中，id 屬性會指定廣播的 ID。
mine boolean
mine 參數可用來指示 API 只傳回已驗證使用者擁有的廣播訊息。如果只要擷取自己的廣播訊息，請將參數值設為 true。
選用參數
broadcastType string
broadcastType 參數會篩選 API 回應，只納入指定類型的廣播訊息。這個參數應用於將 mine 參數設為 true 或使用 broadcastStatus 參數的要求。預設值為 event。

可接受的值為：
  • all - 傳回所有廣播。
  • event：只傳回已排定的活動播送內容。
  • persistent：只傳回永久廣播。
maxResults unsigned integer
maxResults 參數會指定應在結果集中傳回的項目數量上限。可接受的值為 0 到 50 (含頭尾)。預設值為 5。
onBehalfOfContentOwner string
這個參數只能用於適當的授權請求。注意：這個參數僅供 YouTube 內容合作夥伴使用。

onBehalfOfContentOwner 參數代表請求的授權憑證可用來識別 YouTube CMS 使用者，其身分為參數值中指定的內容擁有者。這個參數專供擁有和管理許多不同 YouTube 頻道的 YouTube 內容合作夥伴使用。有了這個平台，內容擁有者只要進行一次驗證程序，就能存取所有影片和頻道資料，而不需針對各個頻道提供驗證憑證。使用者進行驗證時使用的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。
onBehalfOfContentOwnerChannel string
這個參數只能用於適當的授權請求。這個參數只能用於適當的授權請求。注意：這個參數僅供 YouTube 內容合作夥伴使用。

「onBehalfOfContentOwnerChannel」參數可指定影片的 YouTube 頻道 ID。因為要求指定 onBehalfOfContentOwner 參數值時，這是必要參數，而且只能搭配該參數使用。此外，用來授權請求的 CMS 帳戶必須與 onBehalfOfContentOwner 參數指定的內容擁有者連結。最後，onBehalfOfContentOwnerChannel 參數值指定的頻道必須連結至 onBehalfOfContentOwner 參數指定的內容擁有者。

這個參數適用於擁有和管理許多不同 YouTube 頻道的 YouTube 內容合作夥伴。透過這項機制，內容擁有者即可驗證一次參數值，並代表參數值中代表頻道執行動作，而不必為每個個別頻道提供驗證憑證。
pageToken string
pageToken 參數會找出應在結果集中傳回的特定網頁。在 API 回應中，nextPageToken 和 prevPageToken 屬性會識別其他可擷取的網頁。

要求主體

呼叫這個方法時，請勿提供要求主體。

回應

如果成功的話，這個方法會傳回回應內文，其結構如下：

{
  "kind": "youtube#liveBroadcastListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    liveBroadcast Resource
  ]
}

屬性

下表列出顯示在這項資源中的屬性：

屬性
kind string
識別 API 資源的類型。值為 youtube#liveBroadcastListResponse。
etag etag
這項資源的 Etag。
nextPageToken string
可做為 pageToken 參數值的符記，用於擷取結果集的下一頁。
prevPageToken string
可做為 pageToken 參數值的符記，用於擷取結果集中的上一頁。
pageInfo object
pageInfo 物件會封裝結果集的分頁資訊。
pageInfo.totalResults integer
結果集的結果總數。
pageInfo.resultsPerPage integer
API 回應中包含的結果數量。
items[] list
符合要求條件的廣播訊息清單。

錯誤

下表列出 API 可在呼叫此方法時傳回的錯誤訊息。詳情請參閱錯誤訊息說明文件。

錯誤類型 錯誤詳細資料 說明
insufficientPermissions insufficientLivePermissions 這項要求未獲授權，無法擷取現場直播。
insufficientPermissions liveStreamingNotEnabled 獲得授權的使用者無法在 YouTube 上串流播放直播影片。如要瞭解詳情，請前往 https://www.youtube.com/features。

試試看！

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