--- title: Steuerung über die HTTP API url: https://doc2.pstreamer.tv/de/manual/extras/api.html lang: de product: Perfect Streamer version: 2.0.1.264 --- # Steuerung über die HTTP API Alles, was die Weboberfläche tut, kann der Knoten auf eine Anfrage von außen tun: die HTTP API liest und ändert die Konfiguration des laufenden Dienstes und gibt dessen Zustand aus. Zusammen mit der Weboberfläche sind das die einzigen Schnittstellen, die eine Änderung sofort anwenden und das Ergebnis melden. Die Seite vermittelt das Gesamtbild: wo die API zu finden ist, wie sie aufgebaut ist, wie Fehler eintreffen und worin sie sich vom Bearbeiten der Einstellungsdatei unterscheidet. Das Nachschlagewerk zu den einzelnen Anfragen und Schlüsseln steht in eigenen Dokumenten (Referenzdokumente); hier wird es nicht wiederholt. ## Zugang Die API antwortet auf demselben Webserver wie die Administrationsoberfläche. In der ausgelieferten Konfiguration ist das Port `8808`; ist in den Einstellungen überhaupt kein Port angegeben, verwendet der Dienst den eingebauten Wert `43971`. Der TLS-Port ist `43981`, unmittelbar nach der Installation ist TLS jedoch ausgeschaltet und dieser Port wird nicht abgehört ([Anfangseinstellungen](../first_start/index.md#first-start-initial-settings)). Eine eigene Adresse oder ein Präfix der Art */api* hat die API nicht. - **HTTP und HTTPS sind gleichberechtigt.** Die Umleitung vom offenen Port auf TLS betrifft nur die Seiten der Oberfläche; API-Anfragen funktionieren weiterhin über beide Protokolle. - **Die Authentifizierung ist HTTP Digest**, mit denselben Konten wie in der Weboberfläche und denselben Rollen: **Admin** — voller Zugriff, **Restricted admin** — alles lesen sowie einen Stream, seinen Eingang oder seinen Ausgang pausieren, **Viewer** — nur lesen. Ein Schreibvorgang außerhalb der eigenen Rolle wird abgelehnt. Statt eines Passworts lässt sich die Sitzung mit einem Autologin-Schlüssel vorweisen — als Cookie, im Header `X-Auth-Token` oder im Parameter `?auth-token=`. - **Anfragen vom Knoten selbst werden nicht authentifiziert.** Ein Zugriff, der über die Loopback-Schnittstelle (`127.0.0.1`, `::1`) eintrifft, kommt ohne Digest durch und erhält die Rolle **Admin**. Abschalten lässt sich das nicht, eine Einstellung dafür gibt es nicht. Das Zugeständnis hat allerdings Grenzen: von außerhalb des Knotens ist es nicht einzufordern — sich selbst per Header eine Loopback-Adresse unterzuschieben gelingt nicht — und für eine Cross-Origin-Anfrage entfällt es, weil sonst eine auf dem Knoten geöffnete Webseite die gesamte API über `127.0.0.1` ganz ohne Zugangsdaten steuern würde. Zu handeln ist wegen einer einzigen Folge: jeder Prozess auf dem Knoten verfügt ohne Passwort über die Konfiguration. Wird der API ein Reverse-Proxy vorgeschaltet, richten Sie ihn auf eine Nicht-Loopback-Adresse desselben Knotens — dann funktioniert die Authentifizierung wie gewohnt. Ein Proxy, der `127.0.0.1` anspricht, gibt vollen Zugang an alle weiter, deren Anfragen er durchreicht. - **Es gibt nur zwei Methoden** — `GET` und `POST`. Auf jede andere Methode kommt die Antwort „Methode nicht unterstützt“; die Ausnahme ist die Preflight-Anfrage `OPTIONS` des Browsers, die der Server mit einer Erlaubnis beantwortet, sofern der Ursprung der Anfrage zugelassen ist. > **Warnung** > > **Die Rolle beschränkt nur das Schreiben.** Die Rollenprüfung erfolgt bei `POST`-Anfragen; das Lesen ist überhaupt nicht beschränkt, und die Werte kommen unmaskiert zurück, wie sie sind. Ein Konto mit der Rolle **Viewer** sieht sämtliche Passwörter, die Meshwork-Secrets, die Passphrasen der Transporte und die Schlüssel des Inhaltsschutzes — und der Export einer Sicherungskopie der Einstellungen ist ebenfalls ein Lesevorgang, also die gesamte Konfiguration in einer einzigen Anfrage. Die Rolle **Viewer** begrenzt die Möglichkeit, den Knoten zu ändern, nicht den Zugang zu seinen Secrets: legen Sie sie in diesem Bewusstsein an. Die Auslieferung von Streams und des Programmführers läuft auf eigenen Ports und verwaltet keine Einstellungen ([Anfangseinstellungen](../first_start/index.md#first-start-initial-settings)). ## Woraus die API besteht | Familie | Zweck | | --- | --- | | `/config/…` | Lesen und Ändern der Konfiguration. Der Baum der Anfragen bildet weitgehend die Struktur der Einstellungsdatei ab: ein Abschnitt der Datei ist ein Knoten des Baums ([Aufbau des Dokuments](config_file.md#extras-config-file-structure)). Es gibt Abweichungen: das Array der Archivspeicher wird als `/config/dvr-storage` adressiert und die Kanalsätze des Programmführers als `/config/epg-channel-set`, obwohl sie in der Datei innerhalb von `dvr-storage-list` und `epg-server` liegen. | | `/data/…` | Der Zustand des laufenden Dienstes, überwiegend zum Lesen: die Streams und ihre Verarbeitungsketten, die Hardware, der Programmführer, der Systemmonitor, das Protokoll, die Lizenzangaben. Einige Anfragen ändern den Zustand — Zurücksetzen der Statistik, Start eines Suchlaufs, Quittieren eines Alerts; die Konfiguration ändert davon nur eine — das Entfernen eines Meshwork-Peers aus der Domänenübersicht. Fertige Beispielanfragen stehen in [Tagesprogramm im JSON-Format](../streamer/epg/middleware.md#streamer-epg-json) und [Reklamationsassistent](../streamer/analyzer.md#streamer-analyzer-ai). | | `/schema/…` | Referenzlisten im JSON-Format, nur zum Lesen: die von dieser Ausgabe unterstützten Ein- und Ausgangstypen, die Sprachen, die gefundenen Empfangskarten und Transkodergeräte, die Skala der Wichtigkeit und die Codes der Alarme. Mit der Schemadatei der Einstellungen ([Prüfung mit dem JSON Schema](config_file.md#extras-config-file-schema)) haben sie nichts zu tun. | | Einzelne Adressen | Einige Dienstanfragen außerhalb dieser Bäume: Neustart des Dienstes, Export und Wiederherstellung einer Sicherungskopie der Einstellungen, Liste der Netzwerkschnittstellen, Beenden der Sitzung. | ## Wie Fehler eintreffen Einen Fehler auf Anwendungsebene gibt die API mit **HTTP-Code 200** und einem von null verschiedenen Feld `result` im Antwortkörper zurück: ein Wert außer Bereich, eine fehlgeschlagene Prüfung, der Versuch, einen unveränderlichen Schlüssel zu schreiben, die Weigerung, einen für diese Rolle unzugänglichen Schlüssel zu schreiben. Ein Skript, das nur den HTTP-Code prüft, wird deshalb sämtliche solchen Ablehnungen der Reihe nach für Erfolge halten. Werten Sie den Antwortkörper aus. Codes ungleich 200 kommen ebenfalls vor, bedeuten aber etwas anderes: 401 — die Authentifizierung ist nicht erfolgt, 403 — die Rolle ist zur Anfrage selbst nicht zugelassen, 404 — eine solche Anfrage gibt es nicht, 405 — die Methode wird nicht unterstützt. Eine Ablehnung wegen der Rolle trifft also auf zwei verschiedenen Wegen ein: die gesamte Anfrage wird mit Code 403 abgewiesen, ein einzelner unzulässiger Schlüssel dagegen mit einer gewöhnlichen Antwort und einem von null verschiedenen `result`. Einen Wert außerhalb des zulässigen Bereichs **lehnt** die API ab. Genau darin unterscheidet sie sich vom Lesen der Einstellungsdatei, wo ein solcher Wert auf die Bereichsgrenze gesetzt wird ([Wird angenommen, aber nicht so, wie es der Bearbeiter gemeint hat](config_file.md#extras-config-file-tolerated)). Einen unbekannten Schlüssel lehnt die API nicht ab: er wird genau wie beim Lesen der Datei übergangen, die Antwort kommt mit `result` 0, und die einzige Spur bleibt im Protokoll des Knotens. Ein Tippfehler im Schlüsselnamen ist deshalb auch hier nicht sichtbar — Schlüsselnamen werden vorab gegen das Schema geprüft ([Prüfung mit dem JSON Schema](config_file.md#extras-config-file-schema)). ## Änderungen, die einen Neustart brauchen Zwei Änderungen werden erst nach einem Neustart des Dienstes wirksam: die Aktivierung der Lizenz und die Wiederherstellung der Einstellungen aus einer Sicherungskopie. Keine von beiden überlässt den Neustart dem Ermessen des Bedieners: nachdem die Datei angenommen wurde, startet sich der Dienst nach etwa vier Sekunden selbst neu — aufschieben lässt sich das nicht, und während des Neustarts ist der Knoten nicht erreichbar. Die Antworten dieser beiden Anfragen tragen kein Feld `reboot`; in den JSON-Antworten der Konfigurations-API bedeutet es, dass der Knoten bereits in den Neustart geht, und nicht, dass ein Neustart auf einen Befehl wartet. Ebenso, von selbst, startet ein Knoten neu, dessen Lizenz abgelaufen ist. Den Dienst aus eigenem Antrieb neu starten kann man mit einer gesonderten Anfrage, über die Weboberfläche oder mit dem Befehl `sudo systemctl restart pss`. Das Ändern der Abhörports und das Einschalten von TLS erfordern keinen Neustart des Dienstes: er schließt den lauschenden Socket und öffnet ihn erneut, ein Feld `reboot` erscheint in der Antwort nicht. Die auf diesem Port offenen Verbindungen brechen dabei ab, und weiter ist die Verbindung über den neuen Port aufzunehmen. ## API oder Einstellungsdatei | | HTTP API | Die Datei `pss.json` | | --- | --- | --- | | Wann es wirkt | Sofort | Ab dem nächsten Start des Dienstes | | Zustand des Dienstes | Läuft | Gestoppt | | Ergebnis | Wird in der Antwort geliefert | Nur im Protokoll nach dem Start sichtbar | | Wert außerhalb des Bereichs | Wird abgelehnt | Wird auf die Grenze gesetzt | | Unbekannter Schlüssel | Wird stillschweigend ignoriert, `result` 0 | Wird stillschweigend ignoriert, sofern man das Protokoll nicht liest | | Wofür es sich eignet | Punktuelle Änderungen, Automatisierung, Beobachtung | Massenänderungen, Übertragung der Einstellungen zwischen Knoten und Versionen | Die Datei eines laufenden Dienstes zu bearbeiten ist nutzlos und gefährlich: der Dienst überschreibt `pss.json` mit dem, was er im Speicher hält, und tut das nach eigenem Zeitplan — die Änderung verschwindet ohne jede Meldung. Stoppen Sie den Dienst und prüfen Sie die Datei vor dem Start gegen das Schema; das Vorgehen steht in [Einstellungen bearbeiten, prüfen und übertragen](config_editing.md#extras-config-editing). ## Referenzdokumente | Dokument | Inhalt | | --- | --- | | `http_config_api.txt` | Das Nachschlagewerk zur Konfigurations-API: Protokoll, Operationen, der Baum `/config` und eine Beschreibung jedes Schlüssels Punkt für Punkt — Typ, Einschränkungen, Standardwert. | | `http_data_api.txt` | Das Nachschlagewerk zur Zustands- und Statistik-API: der Baum `/data`, die Antwortformate, die Anfragen an das Protokoll und an die Datenbanken. | | `pss_config_file.txt` | Das Nachschlagewerk zum Format der Einstellungsdatei. Die Darstellung für den Bediener ist [Die Einstellungsdatei pss.json](config_file.md#extras-config-file). | | `pss_config_editing.txt` | Die Verfahren zum Bearbeiten, Prüfen und Übertragen der Einstellungen. Ihre Darstellung ist [Einstellungen bearbeiten, prüfen und übertragen](config_editing.md#extras-config-editing). | | `pss.schema.json`, `pss.compat.schema.json` | Eine maschinenlesbare Beschreibung der Einstellungsdatei im Format JSON Schema ([Prüfung mit dem JSON Schema](config_file.md#extras-config-file-schema)). | Die Dokumente sind in englischer Sprache verfasst. Zum Paket gehören sie nicht: auf dem Knoten sind sie nicht vorhanden und dort zu suchen ist zwecklos. All das ist auf der Dokumentationswebsite veröffentlicht, mit einem Verzeichnis je Produktversion: ``` https://doc2.pstreamer.tv/reference/ vier Referenzdokumente https://doc2.pstreamer.tv/schema/ zwei Schemadateien ``` Nehmen Sie das Verzeichnis der Version, die bei Ihnen installiert ist: das Nachschlagewerk einer anderen Ausgabe beschreibt nicht Ihren Knoten. > **Warnung** > > **Abwärtskompatibilität wird nicht garantiert.** Bei einer Aktualisierung können sich sowohl die HTTP API als auch das Schema und das Format der Einstellungsdatei ändern: Bestand und Namen der Schlüssel, Wertebereiche, Form von Anfragen und Antworten. Prüfen Sie Skripte, die mit der API arbeiten, nach jeder Aktualisierung erneut, und nehmen Sie Referenzdokumente und Schema in derselben Version wie die installierte Ausgabe. Daraus folgen drei Regeln für alle, die eine eigene Integration schreiben: - **Binden Sie sich an die Version,** für die das Skript geschrieben wurde, und prüfen Sie sie beim Start. - **Lesen Sie nach dem Schreiben zurück.** Ein Schlüssel, den es in der neuen Ausgabe nicht mehr gibt, wird nicht abgelehnt, sondern ignoriert, und die Antwort meldet dabei Erfolg: ausgerechnet die Anfrage, die ein solches Verschwinden auffangen würde, fängt es nicht auf. - **Ein in der Antwort fehlendes Attribut bedeutet „diese Version meldet es nicht“ und nicht null.** Andernfalls wird aus einer bei der Aktualisierung entfernten oder umbenannten Kennzahl eine glaubwürdige Messung von etwas Nichtexistierendem.