Skip to main content
Приложения дают Craft контролируемый авторизованный доступ к внешним сервисам. Администраторы настраивают приложения в Панель администратора → Craft → Приложения. Пользователи подключают свои аккаунты в Craft → Приложения.
Приложения Craft отличаются от коннекторов Yahont. Коннектор индексирует общее содержимое в знания Yahont. Приложение получает актуальную информацию из внешнего аккаунта пользователя и может выполнять действия в этом сервисе.

Выбор способа настройки

В Yahont сейчас есть встроенные приложения для Slack, Google Calendar, Google Drive, Gmail, Linear, GitHub, HubSpot и Notion. Для каждого встроенного поставщика можно настроить один инстанс на уровне организации. Можно создать несколько пользовательских приложений с разными slug и шаблонами URL.

Настройка встроенного приложения

В Yahont Cloud встроенные приложения предоставляет Yahont. Нажмите Изменить, чтобы настроить разрешения, затем включите приложение на его карточке. При самостоятельном размещении Yahont сначала создайте приложение OAuth у внешнего поставщика. Используйте именно этот redirect URI, заменив хост на ваш домен Yahont:
Схема, хост и путь должны точно совпадать у поставщика и в Yahont. Форма управления приложением запрашивает client ID и client secret OAuth; она не запрашивает токен доступа отдельного пользователя.
При самостоятельном размещении Yahont хост callback берётся из WEB_DOMAIN. Перед подключением пользователей убедитесь, что эта настройка использует публичный домен, зарегистрированный у поставщика.
Создайте приложение Slack и добавьте redirect URI Yahont в OAuth & Permissions. Добавьте следующие User Token Scopes:
Craft действует с токеном пользователя; пользователь-бот не нужен. Скопируйте Client ID и Client Secret из основной информации приложения Slack.
В Google Cloud Console создайте или выберите проект, включите Google Calendar API, настройте экран согласия OAuth и создайте идентификатор клиента OAuth 2.0 типа Web application. Добавьте redirect URI Yahont в Authorized redirect URIs. Craft запрашивает полный доступ к Google Calendar.
В Google Cloud Console включите Google Drive API и Google Docs API, настройте экран согласия OAuth и создайте клиент OAuth 2.0 типа Web application с redirect URI Yahont. Craft запрашивает полную область Drive, чтобы читать, создавать, изменять и удалять файлы; эти операции внутри Craft регулируются политиками действий.
В Google Cloud Console включите Gmail API, настройте экран согласия OAuth и создайте клиент OAuth 2.0 типа Web application с redirect URI Yahont. Craft запрашивает gmail.modify, что охватывает чтение, метки, черновики, корзину и отправку, но не окончательное удаление сообщений.
В Linear откройте Settings → API → OAuth applications, создайте приложение OAuth и добавьте redirect URI Yahont в его callback URL. Craft запрашивает доступ на чтение и запись от имени пользователя для задач, проектов и комментариев.
В GitHub откройте Settings → Developer settings → OAuth Apps, создайте OAuth App и укажите redirect URI Yahont как её authorization callback URL. Craft запрашивает repo, read:org и read:user; область repo включает репозитории, к которым есть доступ у подключающегося пользователя, в том числе приватные.
В аккаунте разработчика HubSpot создайте приложение и добавьте redirect URI Yahont на его вкладке Auth. Настройте доступ на чтение для владельцев, контактов, компаний и сделок. Области записи для контактов, компаний и сделок необязательны, чтобы можно было подключать аккаунты HubSpot только для чтения.
Создайте публичную интеграцию в настройках интеграций Notion и добавьте redirect URI Yahont в OAuth Domain & URIs. Выберите возможности чтения и записи интеграции в Notion; Notion управляет возможностями там, а не через области OAuth.

Добавление и проверка приложения

1

Откройте управление приложением

Откройте Панель администратора → Craft → Приложения. Выберите поставщика в разделе Доступные приложения или Добавить ещё. В Yahont Cloud откройте приложение, настроенное Yahont.
2

Введите учётные данные организации

При самостоятельном размещении Yahont введите client ID и client secret OAuth от поставщика. В Yahont Cloud эти поля управляются Yahont и не отображаются.
3

Проверьте разрешения

Выберите политику для всех действий или откройте Расширенные и задайте политики для каждого действия отдельно. Проверьте каждое действие записи, отправки, удаления и публикации.
4

Включите приложение

Сохраните конфигурацию и убедитесь, что на карточке приложения указано Включено. Отключённые приложения не отображаются пользователям и не могут подставлять учётные данные.
5

Проверьте от имени пользователя

Подключите аккаунт пилотного пользователя в Craft → Приложения. Проверьте чтение и характерную запись, убедитесь, что карточка одобрения понятна, и проверьте результат во внешнем сервисе.

Настройка политик действий

Встроенные приложения определяют каталог узнаваемых действий. У каждого действия одна политика на уровне организации: Встроенный каталог начинается с продуманных значений по умолчанию: многие операции чтения одобряются автоматически, а значимые изменения обычно используют «Спрашивать». Не считайте, что значение по умолчанию подходит вашей организации; проверяйте список действий при включении каждого приложения. Основной переключатель разрешений применяет Автоодобрение или Спрашивать ко всем действиям. Откройте Расширенные, чтобы создать смешанную политику или выбрать Запрещать для отдельных действий.
Если один исходящий запрос соответствует нескольким действиям, побеждает самая строгая подходящая политика: Запрещать, затем Спрашивать, затем Автоодобрение. Запрос к встроенному приложению, не соответствующий действию из каталога, обрабатывается как Спрашивать.
Решение Одобрить на сессию внутри сессии применяется только к подходящим действиям в этой сессии. Оно не меняет политику администратора и не может отменить «Запрещать».

Запланированные задачи и предварительное одобрение

Запланированная задача выполняется без присутствия пользователя. Её владелец может выбрать нужные приложения в разделе Заранее одобренные приложения. Для запущенных сессий этой задачи выбор позволяет действиям «Спрашивать» всего приложения выполняться без одобрения в реальном времени. Предварительное одобрение не отменяет «Запрещать». Поскольку оно относится к приложению, а не к одному действию, держите узкими и запрос задачи, и список её приложений. Yahont создаёт уведомление, когда запланированная задача использует заранее одобренное действие.

Создание пользовательского приложения

Используйте пользовательское приложение для общедоступного HTTP API, которого нет среди встроенных поставщиков. Пользовательское приложение сочетает настройку прокси с ZIP-набором, который учит Craft вызывать API. Например:

Определяйте шаблоны URL узко

В пользовательских приложениях используются глобы URL. Каждый шаблон должен начинаться с http:// или https://, а хост должен быть буквальным. Подстановочные знаки разрешены только после хоста.
Пользовательские приложения нельзя использовать для доступа к частным, loopback, link-local, облачным метаданным и другим непубличным сетевым адресам. Прокси песочницы блокирует внутренние адреса, даже если шаблон URL их включает. Если Craft должен вызывать пользовательский сервис, откройте только намеренно защищённую общедоступную маршрутизируемую конечную точку HTTPS.
Избегайте пересекающихся шаблонов URL между приложениями. Когда один и тот же URL заявлен несколькими приложениями, первым выбирается приложение с наименьшим ID — обычно созданное раньше всех. Отключённое приложение всё равно может занять совпадение до проверки доступности учётных данных, поэтому не полагайтесь на включение или отключение для разрешения пересечений шаблонов.

Настройка учётных данных

В значении заголовка записывайте каждые учётные данные как именованный заполнитель:
Добавьте значение в Учётные данные организации, если все пользователи должны использовать одну и ту же сервисную учётную запись. Оставьте заполнитель без значения организации, если каждый пользователь должен ввести своё значение на странице приложений. Для публичного API, не требующего учётных данных, шаблон заголовка также можно оставить пустым. Исходные учётные данные организации и пользователей шифруются в хранилище под управлением Yahont. Они не копируются в пользовательский набор или рабочее пространство песочницы. После того как запрос проходит проверку, прокси песочницы подставляет подготовленные заголовки при отправке.

Подготовка набора инструкций

Набор использует ту же структуру и правила проверки, что и пользовательский навык:
Имя ZIP-файла становится slug приложения. Поместите корректный SKILL.md в корень архива или прямо внутрь одной внешней папки и проверьте каждый включённый файл. Если используется внешняя папка, держите все файлы приложения внутри неё. По умолчанию лимиты: 25 МБ на распакованный файл и 100 МБ на весь набор. Формат набора и контрольный список проверки см. в разделе Управление навыками Craft.
У пользовательских приложений нет каталога действий. Для подключённого пользовательского приложения каждый запрос, соответствующий шаблону URL источника, считается неуточнённым действием Спрашивать. Администраторы не могут автоматически одобрять или запрещать отдельные операции пользовательского приложения. Отключите приложение, чтобы прекратить его использование, и будьте особенно осторожны, когда пользователи заранее одобряют его для запланированной задачи.

Управление учётными данными и жизненным циклом

Приложения Cloud, которыми управляет Yahont, нельзя удалить, а администраторы не могут изменять их конфигурацию OAuth. Отключите их, если они не должны быть доступны.

Устранение неполадок

Проверьте client ID и secret OAuth, точный redirect URI, включённые возможности API или интеграции и необходимые области. Убедитесь, что экран согласия поставщика не ограничен одобренными тестовыми пользователями или участниками рабочего пространства.
Убедитесь, что на его карточке указано Включено и у пользователя есть доступ к Craft. Обновите страницу приложений. Для пользовательского приложения убедитесь, что набор и конфигурация сохранены успешно.
Проверьте политику администратора для действия и области или возможности, предоставленные внешним аккаунтом. Политику «Запрещать» переопределить нельзя. Запрос «Спрашивать» также может завершиться ошибкой, если пользователь отклонит его или срок одобрения истечёт.
Так и должно быть. Пользовательские приложения используют одно синтезированное действие «Спрашивать» для каждого запроса, соответствующего их шаблонам URL. Они пока не поддерживают политики для отдельных действий.
Проверьте пересекающиеся шаблоны URL. Делайте каждый хост и путь как можно более конкретными. Побеждает приложение с наименьшим ID, когда несколько приложений соответствуют одному URL, в том числе когда это первое приложение отключено.
Убедитесь, что владелец задачи по-прежнему подключён к приложению и выбрал его в разделе Заранее одобренные приложения. Затем проверьте наличие политики «Запрещать» или другого приложения, чем ожидалось в запросе. Исправьте задачу и используйте Запустить сейчас; заблокированный запуск не возобновляется автоматически.

Приложения для пользователей

Покажите пользователям, как подключать аккаунты, направлять Craft и проверять одобрения.

Архитектура Craft

Изучите правила исходящего трафика, внедрение учётных данных и применение одобрений.