API EPG: Mejores prácticas

Este tema proporciona las mejores prácticas para trabajar con la API de EPG de Cloud Playout.

Introducción

La API de EPG devuelve una Guía de programación electrónica XML para un canal de Cloud Playout, útil para mostrar información del programa en su página web o en su aplicación. Este tema proporciona una explicación de cómo funciona la API y recomendaciones para usarla de manera más efectiva.

Estados de canal

Estados activos

  • DRAFT(Cuando la hora de inicio/finalización programada del canal en el futuro)
  • RE-SCHEDULING
  • SCHEDULED
  • STARTING
  • START_ERROR
  • CREATING
  • CREATE_ERROR
  • RUNNING

Estados inactivos

  • DRAFT(Los canales detenidos volverán a entrar en estado BORRADOR)
  • IDLE
  • STOPPING
  • STOP_ERROR
  • START_ERROR
  • DELETING(no habrá registros de EPG; esto podría hacer que la API de EPG devuelva un código de respuesta 500)
  • DELETE_ERROR(no habrá registros de EPG; esto podría hacer que la API de EPG devuelva un código de respuesta 500)

Recomendación de consulta EPG

  • La consulta EPG por defecto (sin ningún parámetro de consulta para start , stop , o límite suministrado) devolverá 100 registros EPG (o todos los registros si hay menos de 100). El número devuelto se puede cambiar configurándolo en el limit parámetro.
  • Se seguirán proporcionando registros de hasta 14 días proporcionando una hora de inicio y una hora de finalización explícitas, y también un valor límite más alto para la consulta EPG.
  • Debido a que el tiempo de procesamiento aumenta exponencialmente con la cantidad de registros a procesar, recomendamos usar una forma paginada de consultar registros EPG (ver Paginación a continuación) para obtener datos masivos.

Paginación

Así es como le recomendamos que pagine sus consultas para una gran cantidad de registros para obtener el mejor rendimiento:

  1. Comience con una solicitud sin parámetros de consulta: 
    https://sm.cloudplayout.brightcove.com/accounts/{account_id}/channels/{channel_id}/epg
    • Si el canal no se está ejecutando, esto devolverá 100 registros desde la hora de inicio del canal o la hora actual, lo que sea posterior.
    • Si el canal está funcionando, los 100 registros serán una mezcla 50/50 de programas históricos y futuros.
  2. Para páginas adicionales de datos, envíe una solicitud con el start conjunto de parámetros igual al stop valor de atributo en el programme etiqueta del último registro devuelto en la respuesta anterior - más 1 segundo.

Ejemplo

Digamos que su primera consulta devuelve una respuesta como esta:

<tv>
	...
	<program channel = "channel_id" start = "20210228000457" stop = "20210228001457">
		<title> en vivo </title>
		<desc> en vivo </desc>
		<length units = "segundos"> 600.0 </length>
		<icon src = "https://img.brightcove.com/cloudplayout/live-icon.jpg" width = "" height = "" />
		<category> en vivo </category>
		<keyword>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjMsInRhZ3MiOiJyb21hbmNlIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6ImFzaWEiLCJzb25ncyI6NX19</keyword>
	</programme>
</tv>

el resaltado stop valor en el último registro es una marca de tiempo en la forma YYYYMMDDhhmmss , por lo que en formato ISO 8601: 2021-02-28 00:14:57.

Añadiendo un segundo a este valor, obtenemos 2021-02-28 00:14:58.

El parámetro de consulta para la siguiente solicitud será: start=2021-02-28%2000%3A14%3A57 - remember that the start (and end) parameter must be URI-encoded.

Para recuperar todos los registros, continúe enviando solicitudes cada vez más start valores hasta que obtenga una respuesta HTTP 422 con el mensaje "El canal no estará en estado de ejecución en la ventana de tiempo solicitada".

Notas adicionales sobre el comportamiento de respuesta de EPG

Las siguientes notas sobre cómo funciona la API de EPG están destinadas a ayudarlo a crear solicitudes que obtendrán la respuesta deseada.

  • La EPG se construye dinámicamente en función del estado actual del canal, por lo que si un canal está en algún estado activo, excepto RUNNING , entonces la EPG producirá datos futuros a partir de la hora de inicio del canal programado.
  • Si un canal está en RUNNING En el estado, la EPG invocada sin ningún parámetro de consulta proporcionará una combinación (división del 50%, con un límite de 100, esto produciría como máximo 50 registros pasados y 50 registros futuros) de datos de horarios pasados y futuros.
  • Cuando detenga o elimine un canal, estará en un INACTIVE Expresar; los futuros registros de EPG no estarán disponibles desde que el canal haya finalizado su ejecución.
    • En tales casos, la EPG devolverá un conjunto de datos vacío o un código de error 422.
    • En caso de que se necesiten datos históricos para cualquiera de los estados inactivos, la solicitud EPG debe tener una hora de inicio / finalización pasada en los parámetros de consulta.
  • Si la solicitud de EPG tiene ambos end tiempo y limit , limit se le dará preferencia y que se generarán muchos registros; en este caso, es posible que reciba registros después de la hora de finalización dada.
  • La start/end la ventana no puede exceder los 14 días. start puede ser 14 días antes de la fecha y hora actual para recuperar una EPG histórica. También puede consultar datos EPG futuros hasta 14 días después de la fecha y hora actual.
  • Si la diferencia entre la hora de finalización proporcionada y la hora de inicio es superior a 14 días, la API genera datos de programación durante solo 14 días desde el momento de la solicitud hasta la hora de finalización programada del canal o 14 días, lo que ocurra primero.
  • Ambas cosas start y end puede aceptar valores de fecha y hora con o sin desplazamientos de zona horaria; si no se incluye ningún desplazamiento de zona horaria, se asume UTC
  • Ambas cosas start y end los valores deben estar codificados con URI.

Razones por las que la API de EPG devolvería un código de error 422

  • La hora de inicio de EPG no puede ser mayor a 14 días desde el inicio del canal o la hora actual, lo que sea mayor
  • La hora de inicio de EPG no puede ser anterior a 14 días antes de la hora actual
  • El intervalo de EPG debe ser menor o igual a 14 días (la hora de inicio y la hora de finalización deben estar dentro del límite de 14 días)
  • El canal estará en estado de funcionamiento en la ventana de tiempo solicitada (EPG solicitada con la hora de inicio más allá de la hora de parada del canal programada) Se debe proporcionar la hora de inicio o debe ser menor que la hora de finalización (hora de inicio <hora de finalización)