API EPG : Les meilleures pratiques

Cette rubrique présente les meilleures pratiques pour travailler avec l'API EPG de Cloud Playout.

Introduction

L'API EPG renvoie un guide de programmation électronique XML pour un canal Cloud Playout, utile pour afficher des informations sur le programme sur votre page Web ou dans votre application. Cette rubrique fournit des explications sur le fonctionnement de l'API et des recommandations pour l'utiliser le plus efficacement possible.

États des canaux

États actifs

  • DRAFT(Lorsque l'heure de début / heure de fin programmée de la chaîne dans le futur)
  • RE-SCHEDULING
  • SCHEDULED
  • STARTING
  • START_ERROR
  • CREATING
  • CREATE_ERROR
  • RUNNING

États inactifs

  • DRAFT(Les canaux arrêtés entreront à nouveau dans l'état DRAFT)
  • IDLE
  • STOPPING
  • STOP_ERROR
  • START_ERROR
  • DELETING(il n'y aura pas d'enregistrements EPG - cela pourrait amener l'API EPG à renvoyer un code de réponse 500)
  • DELETE_ERROR(il n'y aura pas d'enregistrements EPG - cela pourrait amener l'API EPG à renvoyer un code de réponse 500)

Recommandation de requête EPG

  • La requête EPG par défaut (sans aucun paramètre de requête pour start , stop , ou limite fourni) renverra 100 enregistrements EPG (ou tous les enregistrements s'il y en a moins de 100). Le numéro renvoyé peut être modifié en le définissant dans le limit paramètre.
  • Les enregistrements jusqu'à 14 jours seront toujours fournis en fournissant une heure de début et une heure de fin explicites, ainsi qu'une valeur limite plus élevée à la requête EPG.
  • Étant donné que le temps de traitement augmente de façon exponentielle avec le nombre d'enregistrements à traiter, nous vous recommandons d'utiliser une méthode paginée pour interroger les enregistrements EPG (voir Pagination ci-dessous) pour récupérer des données en masse.

Pagination

Voici comment nous vous recommandons de paginer vos requêtes pour un grand nombre d'enregistrements afin d'obtenir les meilleures performances :

  1. Commencez par une requête sans paramètre de requête : 
    https://sm.cloudplayout.brightcove.com/accounts/{account_id}/channels/{channel_id}/epg
    • Si le canal n'est pas en cours d'exécution, cela renverra 100 enregistrements à partir de l'heure de début du canal ou de l'heure actuelle, selon la dernière éventualité.
    • Si la chaîne fonctionne, les 100 enregistrements seront un mélange 50/50 de programmes historiques et futurs
  2. Pour des pages supplémentaires de données, soumettez une demande avec le start jeu de paramètres égal au stop valeur d'attribut dans programme balise du dernier enregistrement retourné dans la réponse précédente - plus 1 seconde.

Exemple

Supposons que votre première requête renvoie une réponse comme celle-ci :

<télévision>
	...
	<program channel = "channel_id" start = "20210228000457" stop = "20210228001457">
		<title> en direct </title>
		<desc> en direct </desc>
		<length units = "seconds"> 600.0 </length>
		<icon src = "https://img.brightcove.com/cloudplayout/live-icon.jpg" width = "" height = "" />
		<category> en direct </category>
		<mot-clé> eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjMsInRhZ3MiOiJyb21hbmNlIiwiY3VzdG9tX21ldGFkYXRhIjImFX21ldGFkYXRhIjImFX21ldGFkYXRhIjImf7InJlbFkYXRhIjImFXword
	</programme>
</télévision >

Le surligné stop la valeur du dernier enregistrement est un horodatage sous la forme YYYYMMDDhhmmss , donc au format ISO 8601: 2021-02-28 00:14:57.

En ajoutant une seconde à cette valeur, on obtient 2021-02-28 00:14:58.

Le paramètre de requête pour la prochaine requête sera alors: start=2021-02-28%2000%3A14%3A57 - remember that the start (and end) parameter must be URI-encoded.

Pour récupérer tous les enregistrements, continuez à envoyer des demandes en augmentant start valeurs jusqu'à ce que vous obteniez une réponse HTTP 422 avec le message "Le canal ne sera pas en cours d'exécution dans la fenêtre de temps demandée".

Notes supplémentaires sur le comportement de la réponse EPG

Les notes suivantes sur le fonctionnement de l'API EPG sont destinées à vous aider à créer des requêtes qui obtiendront la réponse souhaitée.

  • L'EPG est construit dynamiquement en fonction de l'état actuel du canal, donc si un canal est dans un état actif, sauf RUNNING , l'EPG produira les données futures à partir de l'heure de début de la chaîne programmée.
  • Si une chaîne est en RUNNING état, l'EPG invoqué sans aucun paramètre de requête fournira un mélange (répartition de 50 % - avec une limite de 100, cela produirait au plus 50 enregistrements passés et 50 enregistrements futurs) de données d'horaires passés et futurs.
  • Lorsque vous arrêtez ou supprimez une chaîne, elle sera dans un INACTIVE Etat; les futurs enregistrements EPG ne seront pas disponibles puisque la chaîne a terminé sa diffusion.
    • Dans de tels cas, l'EPG renverra soit un ensemble de données vides, soit un code d'erreur 422.
    • Si des données historiques sont nécessaires pour l'un des états inactifs, la demande EPG doit avoir une heure de début/fin passée dans les paramètres de requête.
  • Si la demande EPG a à la fois un end temps et limit , limit aura la préférence et que de nombreux enregistrements seront générés - dans ce cas, vous pourriez recevoir des enregistrements après l'heure de fin donnée.
  • Les start/end la fenêtre ne peut excéder 14 jours. start peut être 14 jours plus tôt que la date-heure actuelle pour récupérer un EPG historique. Vous pouvez également interroger les futures données EPG jusqu'à 14 jours après la date-heure actuelle.
  • Si la différence entre l'heure de fin et l'heure de début fournies est supérieure à 14 jours, l'API ne génère des données de programmation que pendant 14 jours à partir du moment de la demande jusqu'à l'heure d'arrêt programmée du canal ou 14 jours, selon la première éventualité.
  • Les deux start et end peut accepter des valeurs date-heure avec ou sans décalages de fuseau horaire - si aucun décalage de fuseau horaire n'est inclus, l'UTC est supposé
  • Les deux start et end les valeurs doivent être codées en URI.

Raisons pour lesquelles l'API EPG renverrait un code d'erreur 422

  • L'heure de début de l'EPG ne peut pas être supérieure à 14 jours à partir du début de la chaîne ou de l'heure actuelle, selon la plus grande des deux
  • L'heure de début de l'EPG ne peut pas être antérieure à 14 jours avant l'heure actuelle
  • L'intervalle EPG doit être inférieur ou égal à 14 jours (l'heure de début et l'heure de fin doivent être dans la limite de 14 jours)
  • Le canal sera en cours d'exécution dans la fenêtre de temps demandée (EPG demandé avec une heure de début au-delà de l'heure d'arrêt du canal programmée) L'heure de début doit être fournie ou doit être inférieure à l'heure de fin (heure de début < heure de fin)