documentation/pages/api-module.md

Взаимодействие с модулем через API

Доступ к модулю по API контролируется с помощью компонентов APIComponent. Есть несколько типов таких компонентов, каждый из которых отвечает за свой набор функционала.

• Файловый API
• ML-компонент
• Общая работа с пайплайнами
• Отдельный пайплайн

Все API запросы работают по ссылкам вида https://platform.stratpro.hse.ru/pu-username-pa-appname/<api>.

Здесь pu-username-pa-appname - название приложения, оно же указано в пункте namespace во всех компонентах приложения.

Файловый API

Работа с файловым API

URL запросов к файловому API имеют вид https://platform.stratpro.hse.ru/pu-username-pa-appname/files/box-name/<path>.

Здесь box-name - это имя компонента DataBox, к которому обращается запрос.

Файловый API позволяет загружать файлы в файловое хранилище и получать уже загруженные файлы. Загрузка папок со всем содержимым не предусмотрена, в таких случаях предполагается автоматизация запросов на загрузку отдельных файлов.

<path> в запросах к файловому API может быть путём как к файлу, так и к файловой группе (папке). Тип пути определяется так:

1. Если путь состоит из одного сегмента, это файловая группа. .../files/box-name/data - путь к файловой группе data.
2. Если путь состоит из нескольких сегментов, и заканчивается на /, это путь к файловой группе. .../files/box-name/data/images/ - путь к файловой группе data/images.
3. Если путь состоит более, чем из одного сегмента, и заканчивается не на /, это путь к файлоу. .../files/box-name/data/images/example.png - путь к файлу example.png, расположенному в файловой группе data/images

Названия файлов не влияют на то, указывает ссылка на файл или на файловую группу. Например, .../files/box-name/example.png - это путь к файловой группе, а не файлу.

Загрузка файлов через сервис files

Для загрузки файла можно использовать следующий запрос PUT:

curl -X PUT https://platform.stratpro.hse.ru/pu-username-pa-appname/files/box-name/my_dir/my_file.txt -H "Content-Type: application/json" -u "developer:<password>"

Это запрос:

1. К приложению pu-username-pa-appname.
2. К файловому API (у которого endpoint всегда files).
3. К ящику box-name.
4. К пути my_dir/my_file.txt внутри ящика.
5. От имени пользователя модуля developer, пароль которого - <password>.

Даже если запрос верный, сам файл на данном этапе не создаётся. Вместо этого должен прийти ответ в формате JSON:

{
    "name": "pu-username-pa-appname/files/box-name/my_dir/my_file.txt",
    "presigned_put_url": "<Длинная pre-signed ссылка загрузки>"
}

С помощью pre-signed ссылки можно уже загрузить сам файл следующим запросом:

curl -X PUT -T local/path/to/my_file.txt "<Длинная pre-signed ссылка загрузки>"

Здесь local/path/to/my_file.txt - локальный путь к файлу.

Скачивание файлов через сервис files

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

curl -X GET https://platform.stratpro.hse.ru/pu-username-pa-appname/files/box-name/my_dir/my_file.txt -H "Content-Type: application/json" -u "developer:<password>"

Ответ такой же, как при загрузке - pre-signed ссылка в формате json, но теперь на скачивание.

{
    "name": "pu-username-pa-appname/files/box-name/my_dir/my_file.txt",
    "presigned_get_url": "<Длинная pre-signed ссылка скачивания>"
}

GET-запрос к файловой группе возвращает список файлов, которые она содержит.

{
    "name": "pu-username-pa-appname/files/box-name/my_dir/",
    "files": [
        {
            "name": "pu-username-pa-appname/files/box-name/my_dir/file1.png",
            "presigned_get_url": "<Длинная pre-signed ссылка скачивания>"
        },
        {
            "name": "pu-username-pa-appname/files/box-name/my_dir/file2.txt",
            "presigned_get_url": "<Длинная pre-signed ссылка скачивания>"
        }
    ]
}

ML-компонент

ML-компоненты проводят расчёты при получении соответствующих запросов и присылают результат в ответе на запрос.

Каждый развёрнутый ML-компонент содержит OpenAPI спецификацию с информацией о себе. Её можно получить следующим запросом:

curl -X GET https://platform.stratpro.hse.ru/pu-username-pa-appname/API_NAME/modelversion -H "Content-Type: application/json" -u "<username>:<password>"

Тело запроса на выполнения расчёта - это объект с полями, которые в точности копируют поля из функции inference в MLComponent.

• inputs - список входных данных, где каждый элемент - это словарь. Ключи словаря:
  • name - название, произвольная строка, используется в коде модуля. Например, "image".
  • datatype - тип входных данных, одна из строк "FP32", "FP64", "INT32", "FILE", "str", "dict".
  • content_type - тип содержимого файла, если тип входной переменной datatype - это "FILE". Обычно предполагается MIME-type. Например, application/json, text/csv. Для специализированных данных тип может быть любым - bed, docx и так далее.
  • data - строка с путём к входному файлу или одномерный список входных данных соответствующего типа.
  • shape - размерность входной переменной как массива, применимо даже к файлам.
• output_fields - список выходных данных, где каждый элемент - это словарь. Ключи словаря:
  • name, datatype, content_type - аналогично inputs
  • data - строка с путём к выходному файлу. Если передаётся data, результат будет записан в переданный файл. Иначе - записан во временный файл и возвращён в ответ на запрос.
• model_parameters - список пар [name, value], произвольных параметров примитивных типов. Передаются в качестве переменной parameters в расчётную функцию.

Пример запроса

Пример тела запроса к ML-компоненту

{
    "inputs": [
    {
        "name": "image",
        "data": "uploads/test_image.png",
        "datatype": "FILE",
        "content_type": "image/png",
        "shape": [128, 128]
    }
    ],
    "output_fields": [
    {
        "name": "predict",
        "datatype": "INT32"
    }
    ]
}

Запрос, с файлом data.json в его теле и базовой аутентификацией.

curl -X POST -d @data.json https://platform.stratpro.hse.ru/pu-username-pa-appname/API_NAME/predict -H "Content-Type: application/json" -u "<username>:<password>"

Общая работа с пайплайнами

Каждый развёрнутый пайплайн содержит OpenAPI спецификацию запросов к себе. Её можно получить следующим запросом:

curl -X GET https://platform.stratpro.hse.ru/pu-username-pa-appname/pipelines/PIPELINE_NAME/version -H "Content-Type: application/json" -u "<username>:<password>"

Основная работа происходит с конкретными пайплайнами. Из общих команд полезны:

# Получить список пайплайнов
curl -X GET https://platform.stratpro.hse.ru/pu-username-pa-appname/pipelines -H "Content-Type: application/json" -u "<username>:<password>"

# Получить список запусков пайплайнов
curl -X GET https://platform.stratpro.hse.ru/pu-username-pa-appname/trials -H "Content-Type: application/json" -u "<username>:<password>"

Отдельный пайплайн

Пайпланы проводят расчёты при получении соответствующих запросов и сохраняют результаты в файлы.

Структура запроса на запуск пайплайна:

curl -X POST -d @data.json https://platform.stratpro.hse.ru/pu-username-pa-appname/pipelines/PIPELINE_NAME/trials -H "Content-Type: application/json" -u "<username>:<password>"

Тело запроса на выполнения расчёта - это объект с полями, похожими на поля запроса к MLComponent.

• inputs - список входных данных, где каждый элемент - это словарь. Ключи словаря:
  • name - название, произвольная строка, используется в коде модуля. Например, "image".
  • datatype - тип входных данных, одна из строк "FP32", "FP64", "INT32", "FILE", "str", "dict". Должен соответствовать одному из datatypes, определённых в API пайплайна.
  • content_type - тип содержимого файла, если тип входной переменной datatype - это "FILE". Обычно предполагается MIME-type. Например, application/json, text/csv. Для специализированных данных тип может быть любым - bed, docx и так далее.
  • data - строка с путём к входному файлу или одномерный список входных данных соответствующего типа.
  • shape - размерность входной переменной как массива, применимо даже к файлам.
• output_fields - список выходных данных, где каждый элемент - это словарь. Ключи словаря: *
  • data - строка с путём к выходному файлу. Если передаётся data, результат будет записан в переданный файл. Иначе - записан во временный файл и возвращён в ответ на запрос.
• model_parameters - список пар [name, value], произвольных параметров примитивных типов. Передаются в качестве переменной parameters в расчётную функцию.

{
    "inputs": [
        {
            "name": "image",
            "data": "pipeline_data/input/image1.png",
            "datatype": "FILE",
            "content_type": "image/png",
            "shape": 0
        }
    ],
    "output_vars": [
        {
            "name": "report",
            "data": "pipeline_data/output/report/"
        }
    ]
}