Источники и ключи
Как получить каталог или записать заказ во внешний сервис: сохранить адрес сервиса, добавить ключ доступа и настроить запрос в реакции.
На этой странице
Если товары хранятся на вашем сайте, бот может запросить каталог оттуда. А после оформления заказа отправить данные обратно. Для этого у сервиса должен быть API, то есть интерфейс для обмена данными между программами.
В разделе Источники сохраните подключение к сервису, коннектор. Он содержит адрес API и настройки запросов. В разделе Ключи добавьте данные для доступа. В реакциях выбирайте это подключение в действиях «Запрос к источнику» или «Запись в источник». Для сервисов с готовой настройкой сначала проверьте раздел Интеграции.
Коннекторы (Источники)
Раздел Источники → Коннекторы. У коннектора есть Название, Тип, Базовый URL, привязанные учётные данные и заголовки:
| Тип | Для чего нужен | Что учесть |
|---|---|---|
| REST | Для любого HTTP/JSON-API | Укажите адрес и данные доступа внешнего сервиса |
| OzmaDB | Для вашей базы OzmaDB/FunDB | Нужен корневой адрес её REST API; чтение анонимных представлений (view) настраивается проще |
| IMAP | – | Новые IMAP-подключения создать нельзя. Уже сохранённые остаются в списке с пометкой «не поддерживается» и удаляются как обычно |
Кнопка Проверить делает тестовый запрос и показывает статус и задержку (или ошибку): удобно убедиться, что URL и ключ верны.
Учётные данные (Ключи)
Откройте Ключи → Учётные данные. Тип подключения выбирайте по документации сервиса, к которому обращается бот. Ключи хранятся в зашифрованном виде. Доступные способы:
| Способ доступа | Какие значения понадобятся |
|---|---|
| API-ключ | Ключ и имя заголовка, по умолчанию Authorization |
| Bearer-токен | Токен для заголовка Authorization: Bearer |
| OAuth2 (password) | Token URL, Client ID/Secret, логин, пароль, scope |
| OAuth2 (refresh) | Token URL, Client ID/Secret, refresh-токен, scope |
При OAuth2 GetMyBot сам получает временный токен доступа и обновляет его, когда срок заканчивается или сервис отвечает 401. Если сервис выдаёт новый refresh-токен, платформа сохраняет его. При редактировании пустое поле секрета означает «оставить прежнее значение».
Чтение и запись из реакций
- Запрос к источнику (
ds_query): читает данные и сохраняет их во временные данные реакции (ctx). Укажите путь запроса, путь к списку внутри ответа (JSONPath) и имя результата. Например, список товаров, сохранённый под именемproducts, можно передать динамическим кнопкам или циклу по списку. - Запись в источник (
ds_write): отправляет данные (POST/PUT/DELETE) с телом в формате JSON.
Тело запроса, повторы и проверка ответа
Тело POST/PUT-запроса в Веб-запросе и Записи в источник можно собрать как JSON-дерево: у каждого листа свой тип (строка, число, логическое, JSON, null) и подстановки, поэтому число не превращается в строку, а вложенные объекты не требуют ручного экранирования. Пример для заявки:
{
"customer": { "name": "{{param.name}}", "phone": "{{user.phone}}" },
"amount": 4900,
"paid": false
}
Старые текстовые тела продолжают работать; переключатель режима тела покажет текущий и не потеряет введённое.
Повторы (retry_count) срабатывают только при сетевых ошибках, 429 и 5xx; ответы 4xx не повторяются никогда. GET, HEAD, OPTIONS, PUT и DELETE повторяются, а POST и PATCH – только если вы сами задали в запросе заголовок Idempotency-Key: этим вы подтверждаете, что принимающий API отбрасывает дубли по ключу. Платформа всегда отправляет и собственный ключ выполнения шага, но он один повторы POST и PATCH не включает: иначе первая ошибка окончательная, чтобы заказ не создался дважды. Повтор записи с неясным исходом платформа сама не делает для записей через интеграции и CRM; единственное исключение – веб-запрос с вашим заголовком Idempotency-Key.
Проверить ответ коннектора. У REST-подключения в редакторе есть блок Проверить ответ: он отправляет один GET по сохранённому подключению с указанным путём и параметрами (без подстановок) и показывает статус, тип и до 64 КБ тела. Ничего не записывается. Если ответ – JSON, его можно взять как образец для разбора ответа.
Разбор ответа есть у всех действий с внешними данными: веб-запрос, запрос и запись в источник, ИИ, Google Таблица, Google Диск, GetCourse и действия CRM. Источник «Результат действия» – нормализованный результат действия, «Полный ответ» – тело ответа до обработки. Правила применяются целиком: если одно из них не выполнено, ни одна переменная не записывается.
Для разовых запросов без сохранённого коннектора есть действие Веб-запрос, а для скачивания текста страницы: Загрузить URL (см. Действия).
Именованные представления и таблицы OzmaDB
Сохраните подключение типа OzmaDB, затем выберите его в действии Запрос к источнику или Запись в источник и включите режим OzmaDB. Существующие HTTP-запросы сохраняют общий режим и параметры. При явном переключении HTTP-поля остаются в действии, а конфигурация Ozma восстанавливается, пока редактор открыт.
Для чтения задайте статические имена Схемы и Представления (view) или нажмите Загрузить каталог. Кнопка Загрузить ещё добавляет следующие страницы каталога, сохраняя выбранный объект. Загрузить аргументы и поля предлагает аргументы по метаданным. Укажите имя, тип и значение каждого аргумента. При отказе доступа к каталогу или метаданным объект и значения можно ввести вручную.
Представление (view) – сохранённый запрос, который может объединять таблицы и рассчитывать значения. Его выбирают для чтения. Для создания или обновления записи отдельно выберите таблицу Entity.
Пример чтения usr.people_by_team с числовым аргументом team_id:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"view": "people_by_team",
"args": { "team_id": { "type": "number", "value": "42" } },
"limit": 100,
"offset": 0
},
"save_to_ctx": "people"
}
В ctx.people сохранится массив объектов по именам колонок, например [{"id":7,"name":"Алекс"}]. Его можно использовать в цикле по списку и следующих действиях. Размер страницы по умолчанию 100, максимум 500, смещение 0–100000. Для чтения нескольких страниц задайте стабильный порядок в представлении.
Предпросмотр чтения выполняет только чтение, максимум 20 строк. Аргументы должны содержать буквальные значения без подстановок события. Для проверки действия с переменными временно замените их тестовыми значениями. Для записи предпросмотра нет.
Для записи задайте Схему, Таблицу (entity), выберите Создать или Обновить и добавьте типизированные поля. Для обновления нужен положительный ID записи, в том числе из предыдущего действия:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"entity": "person",
"operation": "update",
"id": "{{ctx.person_id}}",
"fields": {
"name": { "type": "string", "value": "{{text}}" },
"active": { "type": "boolean", "value": "true" },
"details": { "type": "json", "value": "{\"tags\":[\"member\"]}" },
"note": { "type": "null", "value": "" }
}
},
"save_to_ctx": "saved_person"
}
Необязательный ключ результата сохраняет ответ транзакции. ID первой записи доступен как ctx.saved_person.results[0].id. Для создания записи используйте insert без id. Пустой объект fields при создании использует значения по умолчанию из entity, при обновлении нужно хотя бы одно поле. Подсказки метаданных исключают вычисляемые поля и поля, запрещённые для выбранной операции. Окончательную проверку прав и ограничений выполняет OzmaDB.
Поддерживаются типы string, number, boolean, json и null. В JSON действия value всегда строка, выбранный тип применяется после подстановки при выполнении. Текст числа сохраняет точность, а string не превращается в JSON-синтаксис. json принимает корректный JSON или точную переменную с JSON. Некорректный JSON вызывает ошибку. Имена схем, объектов и полей задаются статически, без подстановок.
Если после отправки записи ответ потерян, исход операции может быть неизвестен. Перед повтором проверьте данные в OzmaDB. Автоматический повтор без подтверждённой дедупликации небезопасен. Для явных пакетных транзакций остаётся режим HTTP-запрос.
Извлечение любых данных из JSON
В любом из двух действий источника, включая режим HTTP-запрос, откройте Разбор ответа. Включите извлечение и выберите Результат действия после result_path или нормализации Ozma либо Полный ответ до преобразований. Основной ключ результата продолжает работать, правила дополнительно сохраняют значения в явно заданные ключи контекста.
После Предпросмотра чтения строки автоматически появляются в дереве Разбор ответа. Сам просмотр не включает разбор и не меняет параметры действия. Нажмите нужное поле, чтобы создать именованную переменную, или Собрать из всех записей рядом с полем, чтобы получить его значения из всех строк. Например, id превратится в список ids. Новые правила добавляются к существующим, имена автоматически получают уникальные суффиксы. Имя переменной можно изменить, готовую подстановку можно скопировать.
Кнопки Весь ответ, Первая запись и Все ID выбирают частые варианты; последние две доступны для подходящего массива в примере. Для записи ID созданной записи добавляет обязательную переменную created_id без тестовой записи. У нового разбора используется полный ответ, источник уже настроенного разбора сохраняется. Источник можно сменить явно. Пример JSON можно вставить вручную, а путь, режим и разбор вложенных JSON-строк изменить в дополнительных настройках. Большие деревья показываются частично. Пример остаётся вне параметров действия и анализа сценария. Проверить разбор передаёт пример в чистый обработчик разбора, без обращения к источнику.
Пример вложенного ответа:
{
"results": [{ "id": 9007199254740993 }],
"groups": [
{ "members": [{ "name": "Алекс", "active": false }] },
{ "members": [{ "name": "Сэм", "active": true }] }
],
"extra": "{\"status\":{\"ready\":false}}"
}
Добавьте к параметрам действия:
{
"response_parser": {
"source": "raw",
"decode_json_strings": true,
"rules": [
{ "path": "$.results[0].id", "save_to_ctx": "created_id", "mode": "value", "required": true },
{ "path": "$.groups[*].members[*].name", "save_to_ctx": "member_names", "mode": "list" },
{ "path": "/extra/status/ready", "save_to_ctx": "ready", "mode": "value" }
]
}
}
Правила сохраняют точный created_id, получают список ["Алекс","Сэм"] и сохраняют boolean false. После успешного создания записи подставьте {{ctx.created_id}} в ID записи следующего обновления. Можно выбирать строки, числа, boolean, объекты, массивы и null, включая весь корень $. Опция Разбирать JSON внутри строк также раскрывает корректный вложенный JSON в дереве примера.
Поддерживаются .name, ["a.b"] с JSON-экранированием, положительные и отрицательные индексы ([0], [-1]), все элементы ([*], .*), срезы ([1:3]) и JSON Pointer по RFC 6901. Для буквального ключа a/b используйте /a~1b, символ ~ кодируется как ~0, путь / выбирает пустой ключ. Фильтры, выражения и скрипты не поддерживаются.
Режим Одно значение выдаёт ошибку при нескольких совпадениях. Для wildcard-путей выбирайте Список значений. Обязательное правило выдаёт ошибку, если совпадений нет. Необязательное отсутствующее значение становится null, отсутствующий список становится []; найденный null отличается от отсутствия в preview. Все правила вычисляются до изменения контекста. Лимиты: 32 правила, 1024 байта на путь, 1 МиБ на вход и выход, 1000 совпадений на правило, ограниченная глубина и объём обхода.
ID строки и подписи связей Ozma
Параметры чтения Добавить ID основной записи (mainId) и Добавить подписи связанных значений (pun) включаются отдельно. include_main_id: true сохраняет mainId строки, parse_pun: true представляет ячейку с подписью как { "id": 42, "data": "Подпись" }. Конфликт с колонкой mainId вызывает явную ошибку. Полный исходный ответ эти опции не изменяют.
После чтения можно явно переключить источник между строками и полным ответом в Дополнительных настройках разбора. Для уже настроенного полного ответа автоматически показывается соответствующий пример. Изменение объекта, аргументов или флагов чтения очищает старый автоматический пример. Дерево доступно сразу; редактор Пример JSON и Ответ в JSON раскрываются по нажатию. Если пример превышает лимит, сообщение и редактор открываются автоматически.
В следующем действии откройте Подстановки, найдите created_id в группе Из предыдущих действий и нажмите Вставить рядом с {{ctx.created_id}} в поле ID записи или значение аргумента. Переменная вставится на позицию курсора. В списке только результаты предыдущих действий текущего блока; переименование, удаление и перестановка сразу обновляют список.
Поиск в каталоге и метаданные объекта
В новом чтении Ozma поле Ключ результата в контексте расположено перед настройками объекта. При выборе Ozma предлагается ozma_rows, с суффиксом, если это имя уже занято правилом разбора ответа. Существующие имена и вручную очищенное поле сохраняются. Для чтения ключ обязателен, для записи его можно оставить пустым. Если ключ чтения отсутствует, рядом с полем появится конкретная ошибка.
Нажмите Загрузить каталог, чтобы получить 50 представлений для чтения или 50 таблиц для записи. Откройте Объект из каталога и ищите по schema.name во всём удалённом каталоге. Поиск находит буквальную подстроку без учёта регистра: _ и % считаются обычными символами. Загрузить ещё продолжает тот же поиск со смещения, возвращённого сервером. Выбранный объект остаётся видимым при других запросах, а ручные поля схемы и имени доступны даже при отказе доступа. Можно изменить поиск или повторить неудачную загрузку страницы, не вводя объект заново.
Загрузить аргументы и поля показывает обязательность аргументов, цели ссылок, типы колонок и основную таблицу. В блоке Дополнительные метаданные раскрываются неизвестные поля и объекты или массивы, закодированные в JSON-строках. Числовые значения сохраняют точную запись. Для больших или глубоко вложенных данных показывается сообщение о пределе отображения. Просмотр метаданных не меняет действие и правила разбора ответа.
Полный путь настройки Ozma
Форма подключения Ozma отделяет название и тип от адреса экземпляра и сохранённого ключа. Дополнительные HTTP-заголовки свёрнуты, пока список пуст, и раскрываются для настроенных заголовков. Проверка подключения остаётся рядом со своим результатом, ключ выбирается по ссылке. После изменения настроек Ozma прежний статус проверки скрывается. Поздний ответ для старых настроек не подтверждает новые.
В действии подключение и режим расположены рядом, ключ результата остаётся в начале формы, а выбранный schema.view или schema.entity виден над настройками объекта. Поля схемы и имени находятся в блоке Схема и имя вручную. Он свёрнут для настроенного объекта и раскрывается при пустых/некорректных именах или отказе доступа. Аргументы и поля записи редактируются выровненными строками: имя, тип, значение и удаление. Обязательные подсказки из метаданных остаются видимыми, подробная справка открывается через Типы и подстановки.
Параметры чтения объединяют страницы и дополнительные ID/подписи связей. Значения по умолчанию свёрнуты; настроенные нестандартные значения и ошибки страниц раскрывают поля. Проверка чтения сначала показывает нормализованные записи таблицей, затем Ответ в JSON по запросу. Для пустого чтения указано, что проверить; точные значения сохраняются. Нормализованный JSON и Полный ответ OzmaDB доступны отдельными раскрытиями.
В разборе ответа Ozma сгруппированы быстрый выбор, переменные результата, дополнительные настройки селектора, локальный пример/дерево и результаты проверки. Существующие HTTP-действия сохраняют прежнее представление и поведение parser. Дополнительные метаданные раскрываются сразу до полей, без лишнего корневого уровня.
Что дальше
- Действия: действия
Запрос к источникуиЗапись в источник. - Подстановки и формулы: как использовать результат из
ctx. - Интеграции: готовые коннекторы к популярным сервисам.