Update API doc
This commit is contained in:
parent
479115678c
commit
629defd579
1 changed files with 105 additions and 3 deletions
|
|
@ -9,7 +9,7 @@
|
||||||
|
|
||||||
Все API запросы работают по ссылкам вида `https://platform.stratpro.hse.ru/app-name/<api>`.
|
Все API запросы работают по ссылкам вида `https://platform.stratpro.hse.ru/app-name/<api>`.
|
||||||
|
|
||||||
Здесь `app-name` - название приложение, оно же указано в пункте `namespace` во всех компонентах приложения.
|
Здесь `app-name` - название приложения, оно же указано в пункте `namespace` во всех компонентах приложения.
|
||||||
|
|
||||||
|
|
||||||
## Файловый API
|
## Файловый API
|
||||||
|
|
@ -22,8 +22,17 @@ URL запросов к файловому API имеют вид `https://platfo
|
||||||
|
|
||||||
Файловый API позволяет загружать файлы в файловое хранилище и получать уже загруженные файлы. Загрузка папок со всем содержимым не предусмотрена, в таких случаях предполагается автоматизация запросов на загрузку отдельных файлов.
|
Файловый API позволяет загружать файлы в файловое хранилище и получать уже загруженные файлы. Загрузка папок со всем содержимым не предусмотрена, в таких случаях предполагается автоматизация запросов на загрузку отдельных файлов.
|
||||||
|
|
||||||
|
`<path>` в запросах к файловому API может быть путём как к файлу, так и к файловой группе (папке). Тип пути определяется так:
|
||||||
|
|
||||||
#### Пример загрузки и скачивания файла через сервис `files`.
|
|
||||||
|
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`:
|
Для загрузки файла можно использовать следующий запрос `PUT`:
|
||||||
|
|
||||||
|
|
@ -57,12 +66,46 @@ curl -X PUT -T local/path/to/my_file.txt "<Длинная pre-signed ссылк
|
||||||
|
|
||||||
Здесь `local/path/to/my_file.txt` - локальный путь к файлу.
|
Здесь `local/path/to/my_file.txt` - локальный путь к файлу.
|
||||||
|
|
||||||
|
### Скачивание файлов через сервис `files`
|
||||||
|
|
||||||
|
Для скачивания нужно сделать запрос такого же формата, как для загрузки файла, но запрос GET.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -X GET https://platform.stratpro.hse.ru/app-name/files/box-name/my_dir/my_file.txt -H "Content-Type: application/json" -u "developer:<password>"
|
||||||
|
```
|
||||||
|
|
||||||
|
Ответ такой же, как при загрузке - pre-signed в формате json, но теперь на скачивание.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "app-name/files/box-name/my_dir/my_file.txt",
|
||||||
|
"presigned_get_url": "<Длинная pre-signed ссылка скачивания>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
GET-запрос к файловой группе возвращает список файлов, которые она содержит.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "app-name/files/box-name/my_dir/",
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"name": "app-name/files/box-name/my_dir/file1.png",
|
||||||
|
"presigned_get_url": "<Длинная pre-signed ссылка скачивания>"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "app-name/files/box-name/my_dir/file2.txt",
|
||||||
|
"presigned_get_url": "<Длинная pre-signed ссылка скачивания>"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
## ML-компонент
|
## ML-компонент
|
||||||
|
|
||||||
ML-компоненты проводят расчёты при получении соответствующих запросов и присылают результат в ответе на запрос.
|
ML-компоненты проводят расчёты при получении соответствующих запросов и присылают результат в ответе на запрос.
|
||||||
|
|
||||||
Каждый развёрнутый ML-компонент содержит OpenAPI спецификацию запросов к себе. Её можно получить следующим запросом:
|
Каждый развёрнутый ML-компонент содержит OpenAPI спецификацию с информацией о себе. Её можно получить следующим запросом:
|
||||||
|
|
||||||
```
|
```
|
||||||
curl -X GET https://platform.stratpro.hse.ru/app-name/API_NAME/modelversion -H "Content-Type: application/json" -u "<username>:<password>"
|
curl -X GET https://platform.stratpro.hse.ru/app-name/API_NAME/modelversion -H "Content-Type: application/json" -u "<username>:<password>"
|
||||||
|
|
@ -71,6 +114,18 @@ curl -X GET https://platform.stratpro.hse.ru/app-name/API_NAME/modelversion -H "
|
||||||
Тело запроса на выполнения расчёта - это объект с полями, которые в точности копируют поля из функции inference в [MLComponent](mlcmp.md#функция-inference).
|
Тело запроса на выполнения расчёта - это объект с полями, которые в точности копируют поля из функции inference в [MLComponent](mlcmp.md#функция-inference).
|
||||||
|
|
||||||
|
|
||||||
|
* `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-компоненту
|
Пример тела запроса к ML-компоненту
|
||||||
|
|
@ -120,4 +175,51 @@ curl -X GET https://platform.stratpro.hse.ru/app-name/pipelines -H "Content-Type
|
||||||
```
|
```
|
||||||
# Получить список запусков пайплайнов
|
# Получить список запусков пайплайнов
|
||||||
curl -X GET https://platform.stratpro.hse.ru/app-name/trials -H "Content-Type: application/json" -u "<username>:<password>"
|
curl -X GET https://platform.stratpro.hse.ru/app-name/trials -H "Content-Type: application/json" -u "<username>:<password>"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Отдельный пайплайн
|
||||||
|
|
||||||
|
|
||||||
|
Пайпланы проводят расчёты при получении соответствующих запросов и сохраняют результаты в файлы.
|
||||||
|
|
||||||
|
Структура запроса на запуск пайплайна:
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
curl -X POST -d @data.json https://platform.stratpro.hse.ru/app-name/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/"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
```
|
```
|
||||||
Loading…
Reference in a new issue