Web API DocPrinter Broker

Общая логика

Для каждой отправленной задачи назначается id. Этот идентификатор в дальнейшем используется для получения файлов и удаления папки с файлами задачи.

Authentication

Используется аутентификация basic auth (через заголовки запроса). Этот метод не является безопасным без использования защищенного соединения! Существует две роли: client и admin, отличающиеся тем, что admin имеет право обращаться к url/status

SSL connection

Для защиты соединения используется протокол https. Сертификат может быть и самоподписанный, если клиент может верифицировать сертификаты не из доверенного хранилища

API

Ошибки

Ошибки возвращаются в виде форматированной json-структуры

 {
   "response": {
        "operationUuid": {id},
        "errorMessage": {
            "code": -1,
            "message": {message},
        },
    }
}

Если id не было назначено, то будет передано null. HTTP код соответствует логике для случая, когда ошибка пришла от самого брокера, если ошибка пришла от агента и не была отдельно обработана (например, таймаут выполнения макроса), то код будет 200, так как с точки зрения агента всё хорошо (брокер просто проксирует ответ от агента). Поэтому на HHTP код следует ориентироваться скорее для отладки, сам факт ошибки лучше определять по структуре ответа.

GET url/status

Данный запрос возвращает статус брокера (статистику полученных задач с момента старта сервера — requests), пользователей брокера и статистику их задач (users), статусы всех подключенных агентов, разбитых по типам, в каждом из которых дополнительно указывается, есть ли с ним соединение (isAlive), могут ли на него отправляться задачи (isActive) и HTTP-статус ответа на запрос статуса от агента (responseStatus, если соединение есть)

Получить данные по пользователям users можно только при включенной аутентификации 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
          }
        }
      }
    }
  }
}

POST url/command

Данный запрос используется для отправки задачи на сервер. Ответом является 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 STRUCTURE:

files — список {id}/{filename}, которые необходимы для скачивание результатов

RESPONSE EXAMPLE:

{
    "response": {
        "runMacroResponse": {
            "files": [
                "DOCPRINT144-0a6440e3-6754-4e95-98c8-f3c6f6f24db0/file.xlsx"
            ]
        }
    }
}

GET url/download/{id}/{filename}

{id}/{filename} необходимо брать из запроса command, при обращении клиент получает поток для скачивания файла

RESPONSE: application/octet-stream

GET url/delete/{id}

Получив id задачи в ответе (успешном или ошибочном), можно запросить удаление всего каталога с файлами задачи (исходными и результатами). Удаление происходит и автоматически (интервал настраивается на агенте), но этот запрос позволяет удалить, не дожидаясь автоматического сборщика мусора. При успешном выполнении будет как в примере, при неуспешном — соответствующая ошибка

RESPONSE: text/json RESPONSE EXAMPLE:

{
    "status": "success"
}