Svaya / Документация / Программный интерфейс
Программный интерфейс: обзор и вход
Программный интерфейс нужен, чтобы ваша система сама запускала автоматизации платформы, читала их результат, забирала метрики и обращалась к языковым моделям по ключу доступа. Страницы этой группы собраны из договоров интерфейса, поэтому в них те же адреса, поля и коды ответов, что и в самой платформе.
Что можно делать
- Процессы и задания: поставить задание, прочитать его состояние и результат, отменить его, передать сигнал ожидающему шагу.
- Модели: обратиться к языковой модели и получить векторы текстов в привычном формате обращений к моделям: приложению достаточно сменить адрес и ключ.
- Метрики: забрать метрики установки в систему наблюдения вашей компании.
- Внешние системы: завести систему-отправителя заданий и выдать ей права.
Получение токена
Внешняя система входит под своим именем. Администратор заводит ее в кабинете на экране «Внешние системы»: платформа показывает идентификатор вида ext-xxxxxxxx, секрет и адрес выдачи токена. Секрет показывается один раз, сохраните его сразу. Токен выдается по схеме client credentials (OAuth 2.0):
curl -s -X POST "<адрес выдачи токена>" \ -d grant_type=client_credentials \ -d client_id=ext-xxxxxxxx \ -d client_secret="<секрет>"
В ответе поле access_token и срок жизни expires_in в секундах. Токен держат до конца срока и запрашивают заново, когда он истек. Права системы ограничены тем, что разрешил администратор: списком автоматизаций, помощников и возможностями вроде чтения метрик. Запрос за пределами прав получает отказ 403.
Обращения к моделям идут не по токену, а по ключу доступа организации: ключ передается в заголовке Authorization: Bearer и выдается на экране ключей доступа.
Заголовки запросов
| Заголовок | Когда нужен | Назначение |
|---|---|---|
Authorization: Bearer <токен> | Всегда | Токен внешней системы или ключ доступа к моделям. |
Content-Type: application/json | Запросы с телом | Тело всех операций передается в формате JSON. |
Idempotency-Key | Постановка задания | Любая уникальная строка. Повтор запроса с тем же значением не создает второго задания, в ответе приходит то же задание и признак deduplicated. |
traceparent | По желанию | Заголовок трассировки W3C: по нему запрос находят в записях хода запусков. |
Формат ошибок
Ошибки интерфейса платформы приходят с типом application/problem+json по RFC 9457. Код ответа протокола HTTP повторяется в поле status.
| Поле | Описание |
|---|---|
type | Адрес типа ошибки: по нему программа отличает одну ошибку от другой. |
title | Короткое описание типа ошибки. |
status | Код ответа HTTP. |
detail | Пояснение к конкретному случаю. |
trace_id | Идентификатор трассы: назовите его, когда обращаетесь за помощью. |
Обращения к моделям отвечают иначе: тело ошибки имеет вид {"error": {...}}, как принято в совместимом формате, и готовые клиентские библиотеки разбирают его сами.
Запуск задания и чтение результата
Запуск идет в два шага: поставить задание и читать его состояние, пока оно не завершится. Образец ниже ставит задание от имени внешней системы.
curl -s -X POST "https://<адрес установки>/api/core/v1/processes" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: zakaz-10542" \
-d '{
"packageId": "<идентификатор пакета>",
"packageVersion": "<версия пакета>",
"routeId": "<идентификатор маршрута>",
"input": { "orderId": "10542" },
"subject": { "id": "ext-xxxxxxxx", "class": "service" },
"channel": "service"
}'Ответ 201 содержит processId. Состояние читается запросом GET /api/core/v1/processes/<идентификатор задания>. Поле status проходит значения от running до completed, failed или cancelled. Когда задание завершилось, поле result содержит итог:
{
"id": "<идентификатор задания>",
"status": "completed",
"result": {
"outcome": "<код итога>",
"title": "<название итога>",
"data": { "...": "поля, которые объявил маршрут" }
}
}Данные итога лежат в result.data. Если они не помещаются в предел 65 536 байт, поле data пусто, а result.dataTruncated равно true. Полный перечень полей, значений и ответов - на странице «Процессы и задания».