EPG-API: Empfohlene Vorgehensweise

Dieses Thema enthält bewährte Verfahren für die Arbeit mit der Cloud Playout EPG API.

Einleitung

Die EPG-API gibt einen elektronischen XML-Programmierleitfaden für einen Cloud-Playout-Kanal zurück, der zum Anzeigen von Programminformationen auf Ihrer Webseite oder in Ihrer App nützlich ist. Dieses Thema enthält einige Erläuterungen zur Funktionsweise der API und Empfehlungen zu ihrer effektivsten Verwendung.

Kanalzustände

Aktive Zustände

  • DRAFT(Wann die geplante Startzeit/Stoppzeit des Kanals in der Zukunft liegt)
  • RE-SCHEDULING
  • SCHEDULED
  • STARTING
  • START_ERROR
  • CREATING
  • CREATE_ERROR
  • RUNNING

Inaktive Zustände

  • DRAFT(Gestoppte Kanäle gehen wieder in den Status DRAFT über)
  • IDLE
  • STOPPING
  • STOP_ERROR
  • START_ERROR
  • DELETING(es wird keine EPG-Einträge geben - dies könnte dazu führen, dass die EPG-API einen 500-Antwortcode zurückgibt)
  • DELETE_ERROR(es wird keine EPG-Einträge geben - dies könnte dazu führen, dass die EPG-API einen 500-Antwortcode zurückgibt)

Empfehlung für EPG-Abfragen

  • Die EPG-Abfrage (ohne Angabe von Abfrageparametern für start stop, oder Limit) gibt standardmäßig 100 EPG-Datensätze zurück (oder alle Datensätze, wenn es weniger als 100 gibt). Die zurückgegebene Nummer kann durch Einstellen in geändert werden limit Parameter.
  • Datensätze für bis zu 14 Tage werden weiterhin bereitgestellt, indem eine explizite Start- und Endzeit sowie ein höherer Grenzwert für die EPG-Abfrage angegeben werden.
  • Da die Verarbeitungszeit mit der Anzahl der zu verarbeitenden Datensätze exponentiell ansteigt, empfehlen wir eine paginierte Abfrage von EPG-Datensätzen (siehe Seitennummerierung unten) zum Abrufen von Massendaten.

Seitennummerierung

Wir empfehlen Ihnen, Ihre Abfragen für eine große Anzahl von Datensätzen wie folgt zu paginieren, um die beste Leistung zu erzielen:

  1. Beginnen Sie mit einer Anfrage ohne Abfrageparameter: 
    https://sm.cloudplayout.brightcove.com/accounts/{account_id}/channels/{channel_id}/epg
    • Wenn der Kanal nicht ausgeführt wird, werden 100 Datensätze ab der Startzeit des Kanals oder der aktuellen Zeit zurückgegeben, je nachdem, was später eintritt.
    • Wenn der Kanal läuft, sind die 100 Datensätze eine 50/50-Mischung aus historischen und zukünftigen Programmen
  2. Für zusätzliche Datenseiten senden Sie eine Anfrage an die start Parametersatz gleich dem stop Attributwert in der programme Tag des letzten Datensatzes, der in der vorherigen Antwort zurückgegeben wurde - plus 1 Sekunde.

Beispiel

Angenommen, Ihre erste Abfrage gibt eine Antwort wie diese zurück:

<fernseher>
	...
	<program channel = "channel_id" start = "20210228000457" stop = "20210228001457">
		<title> live </ title>
		<desc> live </ desc>
		<Längeneinheiten = "Sekunden"> 600,0 </ Länge>
		<icon src = "https://img.brightcove.com/cloudplayout/live-icon.jpg" width = "" height = "" />
		<Kategorie> live </ Kategorie>
		<Schlagwort > EYJ2AWRLB19PZCI6IJCWNZAXMJE2NDGYMJAYIIWIB3JKZXIIOJMSINRHZ3MIOIJYB21HBMNLIIWIY3VZDG9TX21LDGFKYXRHIJP7INJLZ2LVBII6IMFZAWEILCJZB25NCYI6NX19</schlüsselwort >
	</ programme>
</ tv>

Der hervorgehobene stop Wert im letzten Datensatz ist ein Zeitstempel im Formular YYYYMMDDhhmmss, also im ISO 8601-Format: 2021-02-28 00:14:57.

Addieren wir eine Sekunde zu diesem Wert, erhalten wir 2021-02-28 00:14:58.

Der Abfrageparameter für die nächste Anforderung lautet dann: start=2021-02-28%2000%3A14%3A57 - remember that the start (and end) parameter must be URI-encoded.

Senden Sie weiterhin Anfragen mit zunehmender Anzahl, um alle Datensätze abzurufen start Werte, bis Sie eine HTTP 422-Antwort mit der Meldung "Kanal wird im angeforderten Zeitfenster nicht ausgeführt" erhalten.

Zusätzliche Hinweise zum EPG-Reaktionsverhalten

Die folgenden Hinweise zur Funktionsweise der EPG-API sollen Ihnen helfen, Anfragen zu erstellen, die die gewünschte Antwort erhalten.

  • Das EPG wird dynamisch basierend auf dem aktuellen Status des Kanals erstellt. Wenn sich ein Kanal also in einem anderen aktiven Zustand befindet RUNNING, erzeugt das EPG zukünftige Daten ab der geplanten Startzeit des Kanals.
  • Wenn ein Kanal in ist RUNNING Zustand, wird der EPG, der ohne Abfrageparameter aufgerufen wird, eine Mischung (50% Teilung - mit einer Grenze von 100, dies würde höchstens 50 vergangene Datensätze und 50 zukünftige Datensätze) von vergangenen und zukünftigen Zeitplandaten bereitstellen.
  • Wenn Sie einen Kanal stoppen oder löschen, befindet er sich in einem INACTIVE Zustand; die zukünftigen EPG-Aufzeichnungen sind nicht verfügbar, da der Kanal seinen Lauf beendet hat.
    • In solchen Fällen gibt der EPG entweder einen leeren Datensatz oder einen Fehlercode 422 zurück.
    • Falls historische Daten für einen der inaktiven Zustände benötigt werden, muss die EPG-Anfrage eine vergangene Start-/Endzeit in den Abfrageparametern haben.
  • Wenn eine EPG-Anfrage sowohl eine end Uhrzeit als auch eine Uhrzeit hat limit, limit wird sie bevorzugt und es werden so viele Datensätze generiert. In diesem Fall erhalten Sie möglicherweise Datensätze, die hinter der angegebenen Endzeit liegen.
  • Die start/end Fenster darf 14 Tage nicht überschreiten. start kann 14 Tage vor dem aktuellen Datum/Uhrzeit liegen, um einen historischen EPG abzurufen. Sie können auch zukünftige EPG-Daten bis zu 14 Tage nach dem aktuellen Datum und Uhrzeit abfragen.
  • Wenn die Differenz zwischen der angegebenen Endzeit und der Startzeit mehr als 14 Tage beträgt, generiert die API Plandaten für nur 14 Tage vom Zeitpunkt der Anfrage bis zum geplanten Stopp des Kanals oder 14 Tage, je nachdem, was früher eintritt.
  • Beide start und end kann Datum-Uhrzeit-Werte mit oder ohne Zeitzonen-Offset akzeptieren - wenn kein Zeitzonen-Offset enthalten ist, wird UTC angenommen
  • Beide start und end Werte müssen URI-codiert sein.

Gründe, warum die EPG-API einen 422-Fehlercode zurückgibt

  • Die EPG-Startzeit kann nicht länger als 14 Tage ab dem Kanalstart oder der aktuellen Zeit sein, je nachdem, welcher Wert größer ist
  • Die EPG-Startzeit darf nicht älter als 14 Tage vor der aktuellen Zeit sein
  • Das EPG-Intervall muss kleiner oder gleich 14 Tage sein (Startzeit und Endzeit sollten innerhalb von 14 Tagen liegen)
  • Der Kanal befindet sich im angeforderten Zeitfenster im Status „Wird ausgeführt“ (EPG wird angefordert, wobei die Startzeit nach der geplanten Stoppzeit des Kanals liegt). Die Startzeit muss angegeben werden oder sollte unter der Endzeit liegen (Startzeit und < Endzeit).