LiveBroadcasts: list

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

常見用途

要求

HTTP 要求

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

授權

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

範圍
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 即時影像功能。詳情請參閱「功能使用資格」。

試試看！

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