Для каждой отправленной задачи назначается id. Этот идентификатор в дальнейшем используется для получения файлов и удаления папки с файлами задачи.
Используется аутентификация basic auth (через заголовки запроса). Этот метод не является безопасным без использования защищенного соединения! Существует две роли: client и admin, отличающиеся тем, что admin имеет право обращаться к url/status
Для защиты соединения используется протокол https. Сертификат может быть и самоподписанный, если клиент может верифицировать сертификаты не из доверенного хранилища
Ошибки возвращаются в виде форматированной json-структуры
{
"response": {
"operationUuid": {id},
"errorMessage": {
"code": -1,
"message": {message},
},
}
}
Если id не было назначено, то будет переданно null.
HTTP код соответствует логике для случая, когда ошибка пришла от самого брокера, если ошибка пришла от агента и не была отдельно обработана (например, таймаут выполнения макроса), то код будет 200, так как с точки зрения агента всё хорошо (брокер просто проксирует ответ от агента). Поэтому на HHTP код следует ориентироваться скорее для отладки, сам факт ошибки лучше определять по структуре ответа.
Данный запрос возвращает статус брокера (статистику полученных задач с момента старта сервера — requests), пользователей брокера и статистику их задач (users), статусы всех подключенных агентов, разбитых по типам, в каждом из которых дополнительно указывается, есть ли с ним соединение (isAlive), могут ли на него отправляться задачи (isActive) и HTTP-статус ответа на запрос статуса от агента (responseStatus, если соединение есть)
Получить данные по пользователям users можно только при включенной аутeнтификации basic_auth.
REQUEST BODY: none
RESPONSE: text/json
RESPONSE STRUCTURE:
"requests" — статистика запросов с момента старта сервера
"total" - суммарное количество запросов
"byAgentType" - разбивка запросов по типам агентов
"byAgent" - разбивка запросов по конкретным агентам
"users" - информация о зарегестрированных ползователях и статистика их запросов
Ключ роль пользователей. На данный момент их две: "admin", "client"
"registered" - список зарегестрированных пользователей
"requests" - статистика запросов по пользователям, ключ - имя пользователя, значение - словарь
"total" - суммарное количество запросов
"byAgentType" - разбивка запросов по типам агентов
"VBA" - количество запросов к VBA агентам
"MYOFFICE" - количество запросов к MYOFFICE агентам
"VBA" — словарь подключенных агентов Microsoft Office, где ключи url, а значения — ответ агента + дополнительные поля
"MYOFFICE" — словарь подключенных агентов МойОфис, где ключи url, а значения — ответ агента + дополнительные поля
RESPONSE EXAMPLE:
{
"requests": {
"total": 0,
"byAgentType": {
"VBA": {
"total": 0,
"byAgent": {
"localhost:5000": 0
}
},
"MYOFFICE": {
"total": 0,
"byAgent": {
"localhost:5001": 0
}
}
}
},
"VBA": {
"localhost:5000": {
"XLqueueLength": 0,
"WDqueueLength": 0,
"PPqueueLength": 0,
"foldersOnDisk": 36,
"XLprocesses": 0,
"WDprocesses": 0,
"PPprocesses": 0,
"isAlive": true,
"isActive": true,
"responseStatus": 200
}
},
"MYOFFICE": {
"localhost:5001": {
"jobsSinceStart": 0,
"foldersOnDisk": 0,
"runningSubprocesses": 0,
"activeJobs": 0,
"maxParallelJobs": 10,
"isAlive": true,
"isActive": true,
"responseStatus": 200
}
},
"users": {
"admins": {
"registered": [
"service"
],
"requests": {
"service": {
"total": 0,
"byAgentType": {
"VBA": 0,
"MYOFFICE": 0
}
}
}
},
"clients": {
"registered": [
"client1",
"client2"
],
"requests": {
"client1": {
"total": 0,
"byAgentType": {
"VBA": 0,
"MYOFFICE": 0
}
},
"client2": {
"total": 0,
"byAgentType": {
"VBA": 0,
"MYOFFICE": 0
}
}
}
}
}
}
Данный запрос используется для отправки задачи на сервер. Ответом является json-структура, содержащая массив {id}/{filename}, используя которые можно скачать результат обработки задачи.
REQUEST BODY: multipart
REQUEST STRUCTURE:
agentType — тип агента, на который нужно отправить запрос (на данный момент или VBA, или MYOFFICE)
request — json-структура, содержащая описание запроса (на данный момент только поле с названием нужного макроса — пример ниже)
{
"request": {
"runMacroRequest": {
"macroName": "real_deal_macro_name"
}
}
}
timeoutSec — максимальное время выполнения задачи на сервере в секундах (это ориентир имеено для сервера, а не для клиента)
macroFile — поле с исполняемым файлом (шаблон с макросом или скрипт на python), в заголовке filename должно содержаться имя с расширением, подходящим для выбранного типа агента
dataFiles — поле с произвольными файлами, которые будут положены рядом с файлом с макросом
RESPONSE: text/json
RESPONSE STRUCURE:
files — список {id}/{filename}, которые необходимы для скачивание результатов
RESPONSE EXAMPLE:
{
"response": {
"runMacroResponse": {
"files": [
"DOCPRINT144-0a6440e3-6754-4e95-98c8-f3c6f6f24db0/file.xlsx"
]
}
}
}
{id}/{filename} необходимо брать из запроса command, при обращении клиент получает поток для скачивания файла
RESPONSE: application/octet-stream
Получив id задачи в ответе (успешном или ошибочном), можно запросить удаление всего каталога с файлами задачи (исходными и результатами). Удаление происходит и автоматически (интервал настраивается на агенте), но этот запрос позволяет удалить, не дожидаясь автоматического сборщика мусора. При успешном выполнении будет как в примере, при неуспешном — соответствующая ошибка
RESPONSE: text/json
RESPONSE EXAMPLE:
{
"status": "success"
}