電子節目 API：最佳實務

本主題提供使用 Cloud Playout EPG API 的最佳實踐。

簡介

EPG API 返回 Cloud Playout 頻道的 XML 電子節目指南，可用於在您的網頁或應用程序中顯示節目信息。本主題對 API 的工作原理和最有效地使用它的建議進行了一些解釋。

信道狀態

活動狀態

  • DRAFT（當通道的預定開始時間/停止時間在未來）
  • RE-SCHEDULING
  • SCHEDULED
  • STARTING
  • START_ERROR
  • CREATING
  • CREATE_ERROR
  • RUNNING

非活動狀態

  • DRAFT（停止的通道將再次進入 DRAFT 狀態）
  • IDLE
  • STOPPING
  • STOP_ERROR
  • START_ERROR
  • DELETING（不會有 EPG 記錄-這可能會導致 EPG API 返回 500 個響應代碼）
  • DELETE_ERROR（不會有 EPG 記錄-這可能會導致 EPG API 返回 500 個響應代碼）

EPG查詢推薦

  • 默認情況下的 EPG 查詢（沒有任何查詢參數start , stop， 或者限制提供）將返回 100 個 EPG 記錄（如果少於 100 個，則返回所有記錄）。返回的數字可以通過在limit參數中設置它進行更改。
  • 最多 14 天的記錄仍將通過提供明確的開始時間和結束時間以及 EPG 查詢的更高限制值來提供。
  • 由於處理時間隨著要處理的記錄數量呈指數增長，我們建議使用分頁方式查詢 EPG 記錄（請參閱下面的 分頁 ）來獲取批量數據。

分頁

以下是我們建議您對大量記錄的查詢進行分頁以獲得最佳性能的方法：

  1. 從不使用查詢參數的請求開始： 
    https://sm.cloudplayout.brightcove.com/accounts/{account_id}/channels/{channel_id}/epg
    • 如果通道未運行，這將返回從通道開始時間或當前時間開始的 100 條記錄，以較晚者為準。
    • 如果頻道正在運行，則 100 條記錄將是歷史和未來節目的 50/50 組合
  2. 對於額外的數據頁，請提交請求start參數集等於stop中的屬性值programme上一個響應中返回的最後一條記錄的標記 - 加 1 秒 .

範例

假設您的第一個查詢返回如下響應：

<電視>
	...
	<節目頻道=“頻道ID”開始=“20210228000457”停止=“ 20210228001457 ”>
		<標題>居住</標題>
		<描述>居住</描述>
		<長度單位=“秒”> 600.0< /長度>
		<圖標 src="https://img.brightcove.com/cloudplayout/live-icon.jpg" width="" height=""/>
		<類別>居住</類別>
		<關鍵詞>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjMsInRhZ3MiOiJyb21hbmNlIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6ImFzaWEiLCJzb25ncyI6NX19< /關鍵詞>
	</程序>
 < 電視/電視 >

最後一筆記錄中的突出顯示stop值是表單中的時間戳記YYYYMMDDhhmmss，因此使用 ISO 8601 格式：2021-02-28 00:14:57。

添加一秒鐘這個值，我們得到2021-02-28 00:14:58。

下一個請求的查詢參數將是：start=2021-02-28%2000%3A14%3A57 - remember that the start (and end) parameter must be URI-encoded.

若要擷取所有記錄，請繼續以增加start值的方式傳送要求，直到您收到 HTTP 422 回應，訊息為「通道不會在要求的時間視窗中處於執行中狀態」。

關於 EPG 響應行為的附加說明

以下關於 EPG API 工作原理的說明旨在幫助您創建將獲得所需響應的請求。

  • EPG 是根據信道的當前狀態動態構建的，因此，如果一個通道處於任何活動狀態RUNNING，除了，那麼 EPG 將從計劃的通道開始時間產生未來的數據。
  • 如果通道RUNNING處於狀態，則沒有任何查詢參數調用的 EPG 將提供過去和未來計劃數據的混合（50％ 拆分-限制為 100，最多會產生 50 個過去的記錄和 50 個未來記錄）。
  • 當您停止或刪除頻道時，它將處於一個INACTIVE狀態；未來的 EPG 記錄將無法使用，因為該頻道已經完成運行。
    • 在這種情況下，EPG 將返回空數據集或 422 錯誤代碼。
    • 如果任何非活動狀態需要歷史數據，則 EPG 請求必須在查詢參數中包含過去的開始/結束時間。
  • 如果 EPG 請求同時具有end時間limit，並且limit將優先考慮並且會生成許多記錄-在這種情況下，您可能會在給定結束時間後收到記錄。
  • start /視end窗不得超過 14 天。start可以比當前日期時間早 14 天，以檢索歷史 EPG。您還可以查詢當前日期時間之後最多 14 天的未來 EPG 數據。
  • 如果提供的結束時間和開始時間之間的差異大於 14 天，則 API 僅生成從請求時間到預定通道停止時間的 14 天或 14 天的計劃數據，以較早者為準。
  • start並且end可以接受帶有或不帶時區偏移量的日期時間值-如果不包含時區偏移量，則假定 UTC
  • start和end值都必須是 URI 編碼。

EPG API 返回 422 錯誤代碼的原因

  • EPG 開始時間不能大於從頻道開始或當前時間算起的 14 天，以較大者為準
  • EPG 開始時間不能早於當前時間 14 天
  • EPG Interval must be less than or equal to 14 days (start time and end time should be in 14 days limit)
  • 頻道將在請求的時間窗口中處於運行狀態（EPG 請求的開始時間超過預定的頻道停止時間）需要提供開始時間或應小於結束時間（開始時間 < 時間結束）