EPG API: 모범 사례

이 항목에서는 Cloud Playout EPG API 작업에 대한 모범 사례를 제공합니다.

서문

EPG API는 웹 페이지나 앱에 프로그램 정보를 표시하는 데 유용한 Cloud Playout 채널용 XML 전자 프로그래밍 가이드를 반환합니다. 이 항목에서는 API 작동 방식에 대한 몇 가지 설명과 API를 가장 효과적으로 사용하기 위한 권장 사항을 제공합니다.

채널 상태

활성 상태

  • DRAFT (향후 채널의 예정된 시작 시간/중지 시간)
  • RE-SCHEDULING
  • SCHEDULED
  • STARTING
  • START_ERROR
  • CREATING
  • CREATE_ERROR
  • RUNNING

비활성 상태

  • 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초 .

예

첫 번째 쿼리가 다음과 같은 응답을 반환한다고 가정해 보겠습니다.

<TV>
	...
	 < 프로그램 채널="channel_id” 시작="20210228000457" stop=” 20210228001457“>
		 <  < 제목>라이브/타이틀 >
		 <  < 데스크>라이브/데스크톱>
		 < 길이 단위="초">6000.0  <  /길이 >
		<아이콘 src="https://img.brightcove.com/cloudplayout/live-icon.jpg" 폭="" 높이=""/>
		 <  < 카테고리>라이브/카테고리 >
		 < 키워드 > eyj2awrlb19pzci6ijcwnzaxmje2nd GymjayiiB3jkzxiiojmsinrhz3mioijyb21hbmnliiiii3vzdg9tx21ldgfkyxrHijp7injlz2lvbii6imfzaweilcjzb25nn CYI6nx19  <  /키워드 >
	</프로그램>
 <  /텔레비전 >

마지막 레코드에서 강조 표시된stop값은 양식의YYYYMMDDhhmmss타임스탬프이므로 ISO 8601 형식입니다2021-02-28 00:14:57 .

이 값에 1초를 더하면 다음을 얻습니다2021-02-28 00:14:58 .

그러면 다음 요청의 쿼리 매개변수는 다음과 같습니다. start=2021-02-28%2000%3A14%3A57 - remember that the start (and end) parameter must be URI-encoded.

모든 레코드를 검색하려면 “요청된 시간 창에서 채널이 실행 상태가 아닙니다”라는 메시지와 함께 HTTP 422 응답을 받을 때까지start값이 증가하는 요청을 계속 보내십시오.

EPG 응답 동작에 대한 추가 참고 사항

EPG API 작동 방식에 대한 다음 참고 사항은 원하는 응답을 얻을 수 있는 요청을 생성하는 데 도움이 됩니다.

  • EPG는 채널의 현재 상태를 기반으로 동적으로 구성되므로 채널이 다음을 제외한RUNNING모든 활성 상태에 있으면 EPG는 예정된 채널 시작 시간으로부터 향후 데이터를 생성합니다.
  • 채널이RUNNING상태일 경우 쿼리 파라미터 없이 호출된 EPG는 과거 및 미래 일정 데이터를 혼합 (50% 분할 - 100으로 제한하면 최대 50개의 과거 레코드와 50개의 미래 레코드 생성) 을 제공합니다.
  • 채널을 중지하거나 삭제하면 해당INACTIVE상태가 됩니다. 채널 실행이 완료되었으므로 향후 EPG 레코드를 사용할 수 없습니다.
    • 이러한 경우 EPG는 빈 데이터 세트 또는 422 오류 코드를 반환합니다.
    • 비활성 상태에 대해 기록 데이터가 필요한 경우 EPG 요청에는 쿼리 매개 변수에 과거 시작/종료 시간이 있어야 합니다.
  • EPG 요청에end시간과 이 둘 다 있는 경우 우선 순위가 지정되고 해당 레코드가 많이 생성됩니다. 이 경우 지정된 종료 시간 이후에 레코드를 받을 수 있습니다. limitlimit
  • start / end기간은 14일을 초과할 수 없습니다. start이전 EPG를 검색하려면 현재 날짜-시간보다 14일 더 빠를 수 있습니다. 현재 날짜-시간 이후 최대 14일 동안 미래의 EPG 데이터를 쿼리할 수도 있습니다.
  • 제공된 종료 시간과 시작 시간의 차이가 14일보다 크면 API는 요청 시간부터 예약된 채널 중지 시간까지의 14일 또는 14일 중 빠른 날짜에 대한 일정 데이터를 생성합니다.
  • start및 둘 다 시간대 오프셋이 있거나 없는 날짜-시간 값을 받아들일end수 있습니다. 시간대 오프셋이 포함되지 않은 경우 UTC로 간주됩니다.
  • start및end값은 모두 URI로 인코딩되어야 합니다.

EPG API가 422 오류 코드를 반환하는 이유

  • EPG 시작 시간은 채널 시작 또는 현재 시간 중 더 큰 시간으로부터 14일 이후일 수 없습니다.
  • EPG 시작 시간은 현재 시간보다 14일 이전일 수 없습니다.
  • EPG 간격은 14일 이하여야 합니다(시작 시간 및 종료 시간은 14일 제한 이내여야 함).
  • 채널은 요청된 시간 창에서 실행 상태가 됩니다 (시작 시간이 예정된 채널 중지 시간을 초과하여 EPG를 요청함). 시작 시간을 입력하거나 종료 시간 (시작 시간 < 종료 시간) 미만이어야 합니다.