---
title: Управление через HTTP API
url: https://doc2.pstreamer.tv/ru/manual/extras/api.html
lang: ru
product: Perfect Streamer
version: 2.0.1.264
---

# Управление через HTTP API

Всё, что делает веб-интерфейс, узел умеет делать по запросу извне: HTTP API читает и изменяет конфигурацию работающей службы и отдаёт её состояние. Вместе с веб-интерфейсом это единственные интерфейсы, которые применяют изменение немедленно и сообщают результат.

Страница даёт общее представление: где находится API, как он устроен, как приходят ошибки и чем он отличается от правки файла настроек. Справочник по отдельным запросам и ключам — в отдельных документах (Справочные документы); здесь он не повторяется.

## Доступ

API отвечает на том же веб-сервере, что и интерфейс администрирования. В поставляемой конфигурации это порт `8808`; если порт в настройках не задан вовсе, служба использует встроенное значение `43971`. TLS-порт — `43981`, но сразу после установки TLS выключен и этот порт не слушается ([Начальные настройки](../first_start/index.md#first-start-initial-settings)). Отдельного адреса или префикса вида */api* у API нет.

- **HTTP и HTTPS равноправны.** Переадресация с открытого порта на TLS затрагивает только страницы интерфейса; запросы API продолжают работать по обоим протоколам.
- **Аутентификация — HTTP Digest**, теми же учётными записями, что и у веб-интерфейса, с теми же ролями: **Admin** — полный доступ, **Restricted admin** — чтение всего и постановка на паузу потока, его входа или выхода, **Viewer** — только чтение. Запись, выполненная не по своей роли, отклоняется. Вместо пароля сеанс можно предъявить ключом автовхода — cookie, заголовком `X-Auth-Token` или параметром `?auth-token=`.
- **Запросы с самого узла не аутентифицируются.** Обращение, пришедшее с петлевого интерфейса (`127.0.0.1`, `::1`), проходит без Digest и получает роль **Admin**. Отключить это нельзя, настройки для этого нет. Границы у поблажки есть: снаружи узла её не потребовать — подставить себе петлевой адрес заголовком не выйдет, — и она снимается для кросс-доменного запроса, иначе открытая на узле веб-страница управляла бы всем API через `127.0.0.1` вообще без учётных данных.

  Следствие, на которое нужно реагировать, одно: любой процесс на узле распоряжается конфигурацией без пароля. Если перед API ставят обратный прокси, направьте его на непетлевой адрес того же узла — тогда аутентификация работает как обычно. Прокси, обращающийся к `127.0.0.1`, раздаёт полный доступ всем, чьи запросы он передаёт.
- **Методы только два** — `GET` и `POST`. На любой другой метод приходит ответ «метод не поддерживается»; исключение — предварительный запрос `OPTIONS` от браузера, на который сервер отвечает разрешением, если источник запроса допущен.

> **Предупреждение**
>
> **Роль ограничивает только запись.** Проверка роли выполняется для запросов `POST`; чтение не ограничено ничем, и значения возвращаются как есть, без маскирования. Учётная запись с ролью **Viewer** видит все пароли, секреты Meshwork, парольные фразы транспортов и ключи защиты содержимого, а выгрузка резервной копии настроек — тоже чтение, то есть вся конфигурация одним запросом. Роль **Viewer** ограничивает возможность изменить узел, но не доступ к его секретам: заводя её, исходите из этого.

Раздача потоков и телепрограммы работает на собственных портах и настройками не управляет ([Начальные настройки](../first_start/index.md#first-start-initial-settings)).

## Из чего состоит API

| Семейство | Назначение |
| --- | --- |
| `/config/…` | Чтение и изменение конфигурации. Дерево запросов в основном повторяет структуру файла настроек: секция файла — узел дерева ([Структура документа](config_file.md#extras-config-file-structure)). Расхождения есть: массив хранилищ архива адресуется как `/config/dvr-storage`, а наборы каналов телепрограммы — как `/config/epg-channel-set`, хотя в файле они лежат внутри `dvr-storage-list` и `epg-server`. |
| `/data/…` | Состояние работающей службы, в основном на чтение: потоки и их конвейеры, оборудование, телепрограмма, системный монитор, журнал, сведения о лицензии. Несколько запросов меняют состояние — сброс статистики, запуск сканирования, снятие оповещения; конфигурацию из них правит только один — вывод соседа Meshwork из обзора домена. Готовые примеры запросов есть в разделах [Суточная программа в JSON](../streamer/epg/middleware.md#streamer-epg-json) и [Помощник для рекламаций](../streamer/analyzer.md#streamer-analyzer-ai). |
| `/schema/…` | Справочные перечни в формате JSON только на чтение: типы входов и выходов, поддерживаемые данной сборкой, языки, найденные платы приёма и устройства транскодера, шкала важности и коды тревог. К файлу схемы настроек ([Проверка по JSON Schema](config_file.md#extras-config-file-schema)) отношения не имеют. |
| Отдельные адреса | Несколько служебных запросов вне этих деревьев: перезапуск службы, выгрузка и восстановление резервной копии настроек, список сетевых интерфейсов, завершение сеанса. |

## Как приходят ошибки

Ошибку прикладного уровня API возвращает **кодом HTTP 200** и ненулевым полем `result` в теле ответа: значение вне диапазона, отказ проверки, попытка записать неизменяемый ключ, отказ записать ключ, недоступный этой роли.

Сценарий, который проверяет лишь код HTTP, поэтому будет считать успешными все такие отказы подряд. Разбирайте тело ответа.

Коды, отличные от 200, тоже встречаются, но означают другое: 401 — не пройдена аутентификация, 403 — роль не допущена к самому запросу, 404 — такого запроса нет, 405 — метод не поддерживается. Отказ по роли, таким образом, приходит двумя разными способами: запрос целиком отклоняется кодом 403, а отдельный недопустимый ключ — обычным ответом с ненулевым `result`.

Значение вне допустимого диапазона API **отклоняет**. Тем и отличается от чтения файла настроек, где такое значение приводится к границе диапазона ([Принимается, но не так, как задумал автор правки](config_file.md#extras-config-file-tolerated)).

Неизвестный ключ API не отклоняет: он пропускается ровно так же, как при чтении файла, ответ приходит с `result` 0, и след остаётся только в журнале узла. Опечатка в имени ключа поэтому не видна и здесь — имена ключей проверяют заранее по схеме ([Проверка по JSON Schema](config_file.md#extras-config-file-schema)).

## Изменения, которым нужен перезапуск

Два изменения вступают в силу только после перезапуска службы: активация лицензии и восстановление настроек из резервной копии. Ни то, ни другое не оставляет перезапуск на усмотрение оператора: приняв файл, служба перезапускает себя сама примерно через четыре секунды — отложить это нельзя, и на время перезапуска узел недоступен. Ответы этих двух запросов поля `reboot` не несут; в JSON-ответах конфигурационного API оно означает, что узел уже уходит на перезапуск, а не что перезапуск ждёт команды. Так же, сам, перезапускается узел, у которого истёк срок действия лицензии. Перезапустить службу по своей воле можно отдельным запросом, из веб-интерфейса или командой `sudo systemctl restart pss`.

Смена портов прослушивания и включение TLS перезапуска службы не требуют: служба закрывает слушающий сокет и открывает его заново, поля `reboot` в ответе не будет. Открытые на этом порту соединения при этом разрываются, и дальше подключаться нужно уже на новый порт.

## API или файл настроек

|  | HTTP API | Файл `pss.json` |
| --- | --- | --- |
| Когда действует | Немедленно | Со следующего запуска службы |
| Состояние службы | Работает | Остановлена |
| Результат | Возвращается в ответе | Виден только в журнале после запуска |
| Значение вне диапазона | Отклоняется | Приводится к границе |
| Неизвестный ключ | Игнорируется молча, `result` 0 | Игнорируется молча, если не читать журнал |
| Для чего удобен | Точечные изменения, автоматизация, наблюдение | Массовые правки, перенос настроек между узлами и версиями |

Правка файла работающей службы бесполезна и опасна: служба перезаписывает `pss.json` из того, что держит в памяти, и делает это по собственному расписанию — правка исчезнет без единого сообщения. Останавливайте службу и проверяйте файл по схеме перед запуском; порядок действий — [Правка, проверка и перенос настроек](config_editing.md#extras-config-editing).

## Справочные документы

| Документ | Содержание |
| --- | --- |
| `http_config_api.txt` | Справочник по API конфигурации: протокол, операции, дерево `/config` и постатейное описание каждого ключа — тип, ограничения, значение по умолчанию. |
| `http_data_api.txt` | Справочник по API состояния и статистики: дерево `/data`, форматы ответов, запросы к журналу и базам. |
| `pss_config_file.txt` | Справочник по формату файла настроек. Его изложение для оператора — [Файл настроек pss.json](config_file.md#extras-config-file). |
| `pss_config_editing.txt` | Процедуры правки, проверки и переноса настроек. Их изложение — [Правка, проверка и перенос настроек](config_editing.md#extras-config-editing). |
| `pss.schema.json`, `pss.compat.schema.json` | Машиночитаемое описание файла настроек в формате JSON Schema ([Проверка по JSON Schema](config_file.md#extras-config-file-schema)). |

Документы написаны на английском языке. В состав пакета они не входят: на узле их нет и искать их там не нужно.

Всё это опубликовано на сайте документации, каталогом на каждую версию продукта:

```
https://doc2.pstreamer.tv/reference/      четыре справочных документа
https://doc2.pstreamer.tv/schema/         две схемы
```

Берите каталог той версии, которая у вас установлена: справочник другого выпуска описывает не ваш узел.

> **Предупреждение**
>
> **Обратная совместимость не гарантируется.** При обновлении могут измениться и HTTP API, и схема, и формат файла настроек: состав и имена ключей, диапазоны значений, форма запросов и ответов. Сценарии, работающие с API, проверяйте заново после каждого обновления, а справочные документы и схему берите той же версии, что и установленная сборка.

Из этого следуют три правила для тех, кто пишет свою интеграцию:

- **Привязывайтесь к версии,** под которую написан сценарий, и сверяйте её при запуске.
- **Читайте запись обратно после записи.** Ключ, которого в новой сборке уже нет, не отклоняется, а игнорируется, и ответ при этом сообщает об успехе: единственный запрос, который поймал бы такую пропажу, её не поймает.
- **Отсутствующий в ответе атрибут означает «эта версия его не сообщает», а не ноль.** Иначе снятый или переименованный при обновлении показатель превращается в правдоподобное измерение несуществующего.