Интерфейс прикладного программирования PolyAnalyst (версия 1.0)

Введение

PolyAnalyst API позволяет просто, эффективно и надежно взаимодействовать с сервером PolyAnalyst.

HTTP

PolyAnalyst API предоставляет HTTP-интерфейс и использует JSON в качестве основного формата данных, что позволяет работать с разными языками программирования. Хотя сервер PolyAnalyst поддерживает протоколы HTTP и HTTPS, мы настоятельно рекомендуем вам использовать HTTPS по причинам безопасности.

URL хоста

Все запросы необходимо передавать на your.polyanalyst.server:port/polyanalyst/api/v1.0 (если явно не указано обратное), где your.polyanalyst.server:port представляет собой URL и порт установленного сервера PolyAnalyst (см. настройки Соединения в разделе Руководство по работе с Административным клиентом).

Версия

На настоящий момент доступна первая версия API, в будущем будут поддерживаться и другие версии. Номер версии (v1.0) является частью URL. Более поздние версии гарантировано будут совместимы c более ранними версиями.

Лицензия

Для работы с PolyAnalyst API у вас должна быть соответствующая лицензия.

Чтобы узнать, какие опции предоставляет ваша лицензия

  1. Откройте меню Помощь Аналитического клиента PolyAnalyst;

  2. Выберите пункт О программе и в новом окне откройте вкладку Подключенные опции.

Как показано ниже, опция Использование API включено должна иметь значение "Да".

api license api.rus

Если соответствующей лицензии нет, то при запросе к серверу будет возвращен код ошибки 403.

{
  "error": {
    "code": 403,
    "title": "Forbidden",
    "message": "API license required"
  }
}

Подробнее о кодах ответа см. ниже.

Эпоха Unix

Обратите внимание, что время событий сервера указано как Unix-время, которое отображает количество миллисекунд, прошедших с 1 января 1970 года, 00:00:00 UTC.

Доступ к PolyAnalyst API через cURL

Для доступа к API PolyAnalyst 6.5 вы можете использовать различные утилиты, такие как cURL, Insomnia или Postman, или языки программирования, в зависимости от того, что вам будет удобнее для решения поставленных задач.

cURL представляет собой инструмент командной строки, который используется для передачи данных. cURL основан на использовании библиотеки libcurl – бесплатной библиотеки передачи URL-адресов с клиента на сервер, которая поддерживает различные протоколы передачи данных, например, FTP, FTPS, HTTP, HTTPS, LDAP и т.д.

Все примеры работы с cURL-запросами основаны на использовании curl 7.55.1 (Windows), который по умолчанию поставляется вместе с Windows 10 (сборка 17063).

Перед отправкой запросов через cURL вам необходимо авторизоваться на сервере PolyAnalyst. Для этого используйте следующий запрос в командной строке:

curl --request POST --url "https://your.polyanalyst.server:port/polyanalyst/api/v1.0/login?uname=administrator" --cookie-jar "C:\New folder\my_cookie"

Как можно видеть из приведенного выше примера, для начала указывается название утилиты ("curl"), затем – флаг --request, после которого мы указываем HTTP-метод (POST в нашем случае). Обратите внимание, что для пользователя не указан пароль. Далее указывается флаг --cookie-jar, который обозначает путь к cookie-файлу. Данный файл создается автоматически после авторизации на сервере и необходим для последующего использования. Вы можете указать имя файла самостоятельно, например, “my.cookie”, “my_cookie” и т.д.

Если для пользователя, под которым вы собираетесь войти, требуется пароль, используйте следующий запрос:

curl --request POST --url "https://your.polyanalyst.server:port/polyanalyst/api/v1.0/login?uname=administrator&pwd=123" --cookie-jar "C:\New folder\my_cookie"

Процедура авторизации как отдельная операция описывается здесь.

Не забудьте создать папку для размещения файла cookie.
Если для сервера, с которым вы работаете, не выдан сертификат безопасности, используйте флаг --insecure.

Давайте рассмотрим пример cURL-запроса, который можно использовать для операции 09_Operations_with_projects/21_Operations_with_nodes/03_execute_nodes.html[выполнения узлов проекта].

curl ^
--request POST ^
--url "https://10.0.0.94:8014/polyanalyst/api/v1.0/login?uname=administrator&pwd=123" ^
--header "content-type: application/json" ^
--data "{"""prjUUID""": """f51ee88d-3581-4c3f-bb00-a6d4ffc3811d""", """nodes""": [{"""type""": """DataSource""", """name""": """CarData.csv"""}]}" ^
--cookie "C:\New folder\my_cookie" ^
--insecure

Как вы можете видеть на примере выше, cURL-запрос требует использования различных флагов, например:

  1. Флаг операции --request POST, который означает POST-метод;

  2. Флаг --header, который позволяет указать заголовок запроса;

  3. Флаг данных --data, который позволяет указать данные для отправки на сервер;

  4. Флаг cookie --cookie который задает путь к cookie-файлу, созданному ранее (после процедуры авторизации).

Флаг --cookie может быть заменен флагом -b. Имейте в виду, что этот флаг используется только для чтения данных из cookie-файла.
Используйте полные имена флагов для удобства чтения консоли.

Как вы можете видеть из приведенного выше примера, символ ^ (для Windows) используется для переноса строки.

cURL-запрос также требует определенного синтаксиса. Так, например, при использовании флага --data при передаче данных в формате JSON значение после флага следует передавать с использованием фигурных скобок {} и тройных кавычек.

Вы также можете использовать обратную косую черту \, чтобы экранировать кавычки внутри запроса.

curl --request POST --url "https://localhost:5043/polyanalyst/api/v1.0/project/execute" ^
--header "content-type: application/json" ^
--data "{\"prjUUID\": \"7f418636-35d3-4150-a414-a556252f7f0a\", \"nodes\": [{\"type\": \"DataSource\", \"name\": \"CrimeData.csv\"}]}" ^
-b "C:\New folder\my_cookie"

Вы можете использовать и другие флаги (в соответствии с синтаксисом cURL), информация о которых приведена в официальной документации по cURL.

Если вы получаете сообщение об ошибке типа "The revocation function was unable to check revocation for the certificate.", используйте флаг --ssl-no-revoke.
Использование токенов

Вы также можете использовать API-токены для отправки запросов без процедуры авторизации. Для этого необходимо передавать заголовок x-api-key со значением токена. Токен создается администратором сервера на странице токенов.

Для каждого токена назначается определенный диапазон (область видимости), т.е. ограничение, которое подразумевает, что пользователю разрешено выполнять определенную операцию. Значение области, заданное для того или иного метода, также описано на link:../../../15_For_administrators/04_Administrative_Tool/02_Users_and_gr oups/06_web_admin_api_tokens.html[странице токенов].
Использование токенов должно быть предварительно включено в Настройках сервера Административного клиента (см. опции в секции Логин).

Если токен недействителен, вы получите сообщение об ошибке с кодом 500:

{
  "error": {
    "code": 500,
    "title": "",
    "message": "API key 2OL4ZH8bROWdZ21PXwaZ6 not found"
  }
}

Если для токена не указан соответствующий диапазон, вы также получите сообщение об ошибке с кодом 500:

{
  "error": {
    "code": 500,
    "title": "",
    "message": "API key requested scopes \"view server state\" doesn't meet allowed scopes \"view report\""
  }
}

Если реферер не разрешен, то вернется ошибка 500:

{
  "error": {
    "code": 500,
    "title": "",
    "message": "Referrer is not allowed for API key WsLsi1F0SzFpGjia\/Omn"
  }
}
Комплекты для разработки программного обеспечения (SDK)

Компания Мегапьютер также предоставляет различные наборы средств разработки (SDK) для удобной работы с API PolyAnalyst. Существует 4 SDK, которые представлены для таких языков программирования высокого уровня, как Go, Ruby, Python и Java.

Коды ошибок

При обработке API-запроса сервер PolyAnalyst может вернуть следующие ошибки:

Код Тело ответа и его описание

400

Ошибка запроса

Если в запросе отсутствуют требуемые параметры или используются неизвестные параметры, сервер может выдать код ошибки "400 Bad Request "и дополнительное сообщение:

{
  "error": {
    "code": 400,
    "title": "Bad Request",
    "message": "Invalid query parameters"
    }
}

403

Ошибка авторизации

Большинство запросов могут быть выполнены только после авторизации. Сервер выполняет операции при наличии идентификатора сеанса (SID) – уникального номера, который PolyAnalyst назначает для сеанса.

По умолчанию пользователь с неавторизованной учетной записью не может начать сеанс. Сеанс имеет лимит времени ожидания (см. настройки соединения с сервером в разделе Руководство по работе с Административным клиентом), и по истечении заданного периода неактивности выход из системы будет выполнен автоматически.

Если запрос был отправлен неавторизованным идентификатором сеанса, то сервер выдаст код ошибки "403 Forbidden" и дополнительное сообщение:

{
  "error": {
    "code": 403,
    "title": "Authorization Required",
    "message": "You are not logged in to PolyAnalyst Server."
    }
}

403

Limited access error

Some requests demand the user to have administrator rights, otherwise the "403 error" will be returned.

{
  "error": {
    "code": 403,
    "title": "",
    "message": "Access to this operation is limited to administrators."
    }
}

404

Ошибка "Не найдено"

Ошибки такого типа часто появляются, если запрос имеет недействительный URL. Cервер выдаст код ошибки "404 Not Found". В таком случае проверьте используемый URL.

503

Ошибка "Сервис недоступен"

Иногда (в очень редких случаях) если сервер перегружен, при создании запроса может вернуться код ошибки "503 Service Unavailable".

{
  "error": {
    "code": 503,
    "title": "Service Unavailable",
    "message": "PABUSY"
    }
}

500

Другие типы ошибок (внутренняя ошибка сервера)

Другие возможные ошибки сгруппированы под кодом "500 Internal Server Error". Дополнительное сообщение покажет более подробное описание ошибки. Например, сообщение ниже указывает на недействительные параметры запроса:

{
  "error": {
    "code": 500,
    "title": "",
    "message": "Empty passwords are not supported for LDAP"
    }
}