Skip to content

Вызов и ответ ​

Подключение ​

ПараметрЗначение
Протоколstreamable-http
Формат вызоваjsonrpc-2.0
АвторизацияBearer, токен выдаётся при подключении сервера к платформе

Если схема аргументов, которую сервер объявил в tools/list, запрещает дополнительные поля, платформа перед вызовом убирает аргументы, которых в ней нет. Поэтому новые необязательные аргументы контракта не ломают сервер со строгой схемой. При открытой схеме ничего не убирается.

Принципал ​

Кто вызывает инструмент, сервер узнаёт из принципала — подписанного платформой токена в отдельном заголовке.

ПараметрЗначение
ЗаголовокX-Norm-Principal
Алгоритм подписиES256
Ключи для проверки/.well-known/norm-jwks.json по адресу из утверждения iss
Наибольший срок жизни300 с

Утверждения принципала. Кто пользователь, из какого тенанта, с какими правами, каким способом вошёл и каким токеном провайдера это можно подтвердить.

ПолеОбязательноТипЗачем
audдаstringДля какого сервера выпущен: чужой принципал сервер отвергает.
auth_methodдаstringКак пользователь вошёл на платформу.
correlation_idдаstringСквозной номер запроса: по нему находят вызов в журналах всех сторон.
delegation_idдаstringПо какому поручению агент действует от имени пользователя.
expдаintegerДо какого момента действует, в секундах Unix-времени.
iatдаintegerКогда выпущен, в секундах Unix-времени.
issдаstringКто выпустил принципал: так сервер понимает, чьим ключом проверять подпись.
jtiдаstringУникальный номер принципала: сервер может запоминать его, чтобы не принять один и тот же дважды.
roleдаstringРоль пользователя на платформе.
scopesдасписок stringЧто пользователю разрешено делать.
subдаstringКакой пользователь делает вызов.
tenantдаstringИз какой компании пользователь: данные чужой компании не отдают.
provider_tokenнетstringТокен провайдера входа, если серверу нужно подтвердить личность у него.

Сервер проверяет принципал в два шага. Первый обязателен: подпись по ключам платформы, совпадение aud со своим подключением и срок действия. Второй — по выбору бизнеса: подтвердить у провайдера по auth_method и provider_token, что пользователь ещё действующий. Токен провайдера разрешён только для этой проверки, не для доступа к данным провайдера от имени пользователя; в журналах и отчётах он маскируется.

Ответ инструмента ​

Успешный ответ любого инструмента каталога — это structuredContent из двух частей: обязательного конверта и данных инструмента в поле data. Поля data описаны у каждого инструмента в разделе «Каталог инструментов».

Конверт ответа. Обязательная часть успешного ответа любого инструмента каталога: откуда данные, насколько свежи, есть ли продолжение. Дополнительные поля разрешены: ответ сервера может быть шире контракта.

ПолеОбязательноТипЗачем
freshnessдаFreshnessНа какой момент данные верны и не устарели ли они.
source_refsдасписок SourceRefОткуда взяты данные: чтобы сослаться на источник.
pageнетPageЕсть ли продолжение и как его запросить.

SourceRef ​

Ссылка на источник. Система-источник, ключ записи в ней и человекочитаемая подпись.

ПолеОбязательноТипЗачем
refдаstringКакая запись в этой системе: чтобы найти её там.
sourceдаstringИз какой системы данные.
labelнетstringПодпись для человека, если ссылку нужно показать.

Freshness ​

Свежесть. Момент данных, срок годности в секундах и признак устаревания.

ПолеОбязательноТипЗачем
as_ofдаstring (date-time)На какой момент данные верны.
staleдаbooleanУстарели ли данные; true — на них лучше не опираться без проверки.
ttl_secдаintegerСколько секунд данные можно считать свежими.

Page ​

Страница. Есть ли ещё данные и непрозрачный курсор для следующей страницы.

ПолеОбязательноТипЗачем
has_moreдаbooleanЕсть ли ещё страницы.
next_cursorнетstringЧто передать в cursor, чтобы получить следующую страницу.

Постраничная выдача ​

Инструмент с пометкой «списковый» отдаёт данные страницами. Он обязан принимать аргументы limit и cursor и возвращать в конверте page. Курсор непрозрачен: клиент передаёт page.next_cursor как есть, не разбирая его.

ListInput ​

Вход спискового инструмента. Размер страницы и непрозрачный курсор. Обязателен у инструмента, помеченного list: true.

ПолеОбязательноТипЗачем
cursorнетstringКакую страницу прислать: next_cursor из прошлого ответа. Без него — первую.
limitнетintegerСколько записей прислать на одной странице.

Пределы ​

ПределЗначениеЧто ограничивает
max_result_chars32000символов в сериализованном structuredContent ответа
max_page_size200элементов на странице спискового инструмента
principal_max_ttl_sec300секунд жизни подписанного принципала
transcript_default_chars12000символов в окне расшифровки по умолчанию
transcript_max_chars24000символов в окне расшифровки наибольшее