API MasterSCADA 4D > Подключение к исполнительной системе по JSON > HTTP API MasterPLC > Формат запросов, типы данных и коды ошибок

Общие правила транспорта для всех методов HTTP/JSON API: как формируется запрос, какими типами передаются значения параметров и какие поля и коды возвращаются в ответе.

Содержание

•Запрос

•Типы данных

•Ответ

•Коды ошибок

Запрос

•Все методы вызываются запросом POST /Methods/<MethodName>.

•Тело запроса — JSON-объект.

•Для всех методов, кроме Login, нужна действующая сессия. sessionId передаётся в теле JSON; FastCGI также проверяет CGI-переменную HTTP_SESSION_ID, соответствующую HTTP-заголовку Session-Id.

•Прикладной результат возвращается с HTTP-статусом 200, в том числе при ненулевом code.

Типы данных

Значения параметров в запросах и ответах передаются следующими типами:

Тип параметра	JSON-представление
BOOL, перечисление	bool; для перечислений — целочисленный индекс значения
Числовые (INT, DINT, REAL, WORD и т. п.)	number
TIME	number — число миллисекунд
TOD	number — число миллисекунд с начала суток
DATE, DT	number — число миллисекунд с 1 января 1970 года, 0:00 UTC
STRING	string
Массив	JSON-массив значений соответствующего типа
Структура	JSON-объект с полями

Ответ

Ответ всегда содержит числовое поле code: 0 означает успех, любое другое значение — код ошибки. Значение сериализуется как беззнаковое десятичное число; тот же код в шестнадцатеричном виде дублируется полем hex.

Успешный ответ обработчика дополнительно содержит поля метода и, как правило, serverTime:

{
"serverTime": 1718000000000,
"code": 0
}

Если ошибку вернул обработчик метода, в ответ добавляются hex и codeDescription:

{
  "hex": "0x801F0000",
  "codeDescription": "Доступ запрещён",
  "code": 2149515264
}

Если запрос отклонён шлюзом mplc_fcgi до вызова метода (ошибка разбора JSON или проверки сессии), ответ содержит errorText и не содержит serverTime и codeDescription:

{
  "errorText": "Document is empty",
  "code": 2159411200,
  "hex": "0x80B60000"
}

Поля ответа:

Поле	Тип	Когда присутствует	Описание
code	number	всегда	Числовой прикладной результат; 0 означает успех
serverTime	number	обработчик метода был вызван	Время сервера, Unix-время в миллисекундах
hex	string	code не равен 0	Тот же код в шестнадцатеричном виде
codeDescription	string	ошибку сформировал обработчик метода	Локализованное описание кода
errorText	string	запрос отклонён шлюзом до вызова метода	Текст ошибки JSON, сессии или другого раннего этапа обработки

Коды ошибок

Коды соответствуют статус-кодам стандарта OPC UA. Успех — OpcUa_Good (0x00000000, поле code: 0). Коды ошибок начинаются со старшего байта 0x80.

Константа	HEX	Когда возвращается
OpcUa_BadUnexpectedError	0x80010000	Непредвиденная ошибка
OpcUa_BadInternalError	0x80020000	Внутренняя ошибка сервера
OpcUa_BadSyntaxError	0x80B60000	Тело запроса не разобрано JSON-парсером; также CreateMonitoredEvents при ошибке в условии фильтра
OpcUa_BadEncodingLimitsExceeded	0x80080000	Ответный пакет превышает ограничение по размеру
OpcUa_BadMethodInvalid	0x80750000	Метод запроса не опознан
OpcUa_BadSubscriptionIdInvalid	0x80280000	Передан недействительный код подписки
OpcUa_BadMonitoredItemIdInvalid	0x80420000	В DeleteMonitoredEvents / DeleteMonitoredDataItems передан недействительный Id параметра или выборки
OpcUa_BadNodeIdUnknown	0x80340000	В CreateMonitoredDataItems / WriteData / CallPOU передан недействительный адрес переменной (возвращается отдельно по каждому узлу)
OpcUa_BadTooManySubscriptions	0x80770000	Превышен лимит подписок (сейчас не ограничен)
OpcUa_BadTimeout	0x800A0000	Превышен таймаут синхронной обработки в ходе запроса (например, чтения архива)
OpcUa_BadConditionNotShelved	0x80D20000	AcknowledgeEvents: сообщение нельзя квитировать, по нему уже выдано новое
OpcUa_BadConditionBranchAlreadyAcked	0x80CF0000	AcknowledgeEvents: сообщение уже квитировано ранее
OpcUa_BadFilterOperandInvalid	0x80490000	CreateMonitoredEvents: ошибка в условии фильтра
OpcUa_BadIdentityTokenInvalid	0x80200000	Login: неверные учётные данные
OpcUa_BadUserAccessDenied	0x801F0000	Недостаточно прав на действие (вход, чтение или запись параметра, вызов ФБ и т. п.)
OpcUa_BadUserAccessDenied_PasswordExpired	0x801F0001	Login: логин и пароль верны, но срок действия пароля истёк — нужна смена
OpcUa_BadUserAccessDenied_UserBlocked	0x801F0002	Login: логин и пароль верны, но пользователь заблокирован
OpcUa_BadUserAccessDenied_NotAllowedTime	0x801F0003	Login: вход вне разрешённого пользователю диапазона рабочего времени
OpcUa_BadUserAccessDenied_NotAllowedAddress	0x801F0004	Login: вход с незаданного для пользователя адреса клиента
OpcUa_BadUserAccessDenied_NeedChangePassword	0x801F0005	Требуется смена пароля (установлен флаг сброса)
OpcUa_BadUserAccessDenied_DisabledMultiplyLogin	0x801F0006	Одновременный вход того же пользователя запрещён
OpcUa_BadUserAccessDenied_NewPasswordNotValid	0x801F0007	Новый пароль не соответствует требованиям
OpcUa_BadUserAccessDenied_NoShiftAssigned	0x801F0008	Пользователю не назначена смена (при включённом контроле смен)
OpcUa_BadSessionIdInvalid	0x80250000	Любой метод, кроме Login: не передан корректный sessionId или истекло время сессии
OpcUa_BadTooManySessions	0x80560000	Превышено максимальное число подключённых клиентов
OpcUa_BadServiceUnsupported	0x800B0000	Сервер не поддерживает визуализацию или при старте конфигурации возникла ошибка
OpcUa_BadShutdown	0x800C0000	Сервер в состоянии перезагрузки конфигурации
OpcUa_BadDataUnavailable	0x809E0000	Недоступно подключение к БД или стороннему серверу
OpcUa_BadNotFound	0x803E0000	GetTaskStatistics: задача не найдена