Власні інструменти: підключення вашого API

Для розробників, у коді: опис одного HTTP-виклику до вашого API, щоб помічник відповідав із живих даних — кожне поле інструмента, як розміщуються аргументи, параметр мови, область дії, ліміти і політика вихідних з'єднань.

Власний інструмент — це один HTTP-виклик до вашого API, описаний раз у панелі. Помічник вирішує з опису, коли його викликати, заповнює оголошені вами аргументи і відповідає з результату. Для даних, надто великих чи надто свіжих для індексації: каталог, статус замовлення, місце, яке хвилину тому було вільне.

Ця сторінка — довідник. Щоб зібрати інструмент від самого ендпоінта, почніть із покрокового прикладу.

Власні інструменти входять у тариф Growth і вищі. На тарифі без них панель про це каже, а помічник не викликає побудованих вами.

У панелі: Інструменти → Новий інструмент (Інструменти та події). Ця сторінка — той самий інструмент поле за полем, як його зберігає API.

Поля

Поле	Що це
`name`	slug, унікальний у межах сайту — назва, яку бачить модель
`display_name`	підпис у панелі
`enabled`	вимкнений інструмент не прив’язується
`description`	коли його викликати. Єдиний сигнал для моделі: пишіть відкрито («пошук у каталозі товарів за словами відвідувача»), ніколи як закритий перелік значень
`method`	`GET` або `POST`
`url`	з `{param}` для шляху і плейсхолдерами `{{…}}` (Плейсхолдери); https, з хостом
`headers`, `query_params`	статичні значення, плейсхолдери дозволені
`body_template`	JSON-каркас для POST; плейсхолдери підставляються у вкладені рядки, ніколи в ключі
`timeout_ms`	за замовчуванням 5000, під час виконання обмежується 10000
`parameters`	аргументи, які заповнює модель — нижче
`response_description`	що означає відповідь; ставиться перед тілом, яке читає модель: «список товарів із назвою, ціною і посиланням»
`response_path`	шлях через крапку до важливої частини відповіді (`data.items`); без гарантій — при промаху береться все тіло; індексів списків немає
`languages`, `language_param`, `language_param_location`	якими мовами відповідає ваш API і куди класти обрану — заповнює рантайм, ніколи модель, нижче
`cache_answers`	дозволити віддавати повторне перше питання з кешу відповідей першого ходу (вимкнено за замовчуванням: дані живого інструмента свіжі на кожному виклику). Це не кеш відповіді вашого сервера — для того є `Cache-Control` (Кешування відповідей)
`scope`, `screens`	`global` прив’язується на кожному ході; `screen` — лише на екранах (джерелах із маршрутами чи URL сторінки), що його називають
`agent`	один помічник сайту або всі
`emits_event`	детерміновано викликати подію на непорожній результат — Власні події

Параметри

Кожен параметр — { name, type, description, required, location }, до 20.

Ключ	Значення
`type`	`string` · `number` · `integer` · `boolean` · `array`
`location`	`query` (за замовчуванням) · `body` · `path` · `header`
`required`	за замовчуванням false. Обов’язковий параметр — тверда гарантія: зробіть пошуковий запит обов’язковим, інакше модель може викликати інструмент без нічого й вивантажити весь каталог

Куди що лягає: query зливається з рядком запиту URL (список стає повторюваними параметрами); header надсилається рядком; body — ключ верхнього рівня JSON-тіла; path замінює {name} в URL із percent-кодуванням. Аргументи перевіряються за оголошеними типами.

Параметр мови

Якщо ваш API відповідає кількома мовами, перелічіть їх у languages і назвіть параметр у language_param. Рантайм заповнює його сам — мовою відвідувача, коли її підтримують і сайт, і ваш API, інакше основною мовою сайту — і прибирає з аргументів моделі, тож вибір ніколи не є здогадкою. Порожній languages означає одномовний API, який завжди отримує основну мову сайту. Порожній результат 2xx від GET без параметра мови повторюється раз із рядковими аргументами, перекладеними мовою інструмента.

Перевірка

Блок Тест на формі інструмента (кнопка Запустити) робить справжній виклик із прикладами параметрів і показує сиру відповідь, а з прив’язаною подією — що було б надіслано. Кеш вона не використовує ніколи: кешована перевірка сказала б, що сервер працює, коли він може й не працювати. Ліміт — 30 на хвилину на власника.

Ліміти


викликів за хід	3 (повтор із перекладом рахується)
таймаут	ваш `timeout_ms`, щонайбільше 10 с; виклик, що триває довше, скидається, і помічник відповідає без нього
розмір відповіді	256 KB, обрізається
одночасних викликів	8 на процес
інструментів і подій, прив’язаних за хід	12, за назвою — тримайте `global` інструментів мало, а решту прив’язуйте до екранів, тоді власні інструменти екрана завжди вміщаються
інструментів на сайт	за тарифом: 6 / 8 / 11 глобальних і 50 / 150 / 500 екранних на Growth / Pro / Business

Політика вихідних з’єднань

Кожен виклик — від моделі, проактивний, перевірка чи доставка — проходить ту саму політику до відправлення:

лише https;
хост розв’язується в момент виклику, і кожна отримана адреса має бути публічною: приватні, loopback, link-local, зарезервовані й multicast діапазони відхиляються, і хост, який не розв’язується, теж;
редиректи не виконуються;
тіло читається до ліміту розміру.

Білий список на рівні платформи існує для наших власних хостів; це не налаштування власника. Стабільна вихідна IP-адреса, яку власники могли б додати в білий список, запланована, але не збудована: сьогодні виклики йдуть з наших серверів, а не з однієї адреси.

Що бачить модель

Моделі повідомляють ваш response_description, потім відповідь, обрізану за response_path. 401 чи 403 від інструмента з {{user}} повідомляється моделі як «відвідувач, схоже, не увійшов». Секрети й токен користувача ніколи не з’являються в тому, що читає модель.