> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Приложения

> Настройка внешних сервисов, учётных данных и политик действий для Craft

Приложения дают Craft контролируемый авторизованный доступ к внешним сервисам.
Администраторы настраивают приложения в **Панель администратора → Craft → Приложения**.
Пользователи подключают свои аккаунты в **Craft → Приложения**.

> [!NOTE]
>
> Приложения Craft отличаются от коннекторов Yahont. Коннектор индексирует общее содержимое в знания Yahont.
> Приложение получает актуальную информацию из внешнего аккаунта пользователя и может выполнять действия в этом сервисе.

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

| Тип приложения | Конфигурация организации | Подключение пользователя |
| - | - | - |
| **Встроенное в Yahont Cloud** | Yahont управляет клиентом OAuth. Администраторы включают приложение и задают политики действий. | Каждый пользователь проходит процесс OAuth поставщика. |
| **Встроенное при самостоятельном размещении Yahont** | Администратор создаёт приложение OAuth у поставщика, затем вводит его client ID и secret в Yahont. | Каждый пользователь проходит процесс OAuth поставщика. |
| **Пользовательское приложение** | Администратор определяет шаблоны публичных URL, заголовки аутентификации, учётные данные и набор инструкций. | Пользователи вводят значения учётных данных, не предоставленные организацией. |

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

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

В Yahont Cloud встроенные приложения предоставляет Yahont. Нажмите **Изменить**, чтобы настроить разрешения,
затем включите приложение на его карточке.

При самостоятельном размещении Yahont сначала создайте приложение OAuth у внешнего поставщика.
Используйте именно этот redirect URI, заменив хост на ваш домен Yahont:

```text theme={null}
https://yahont.example.com/craft/v1/apps/oauth/callback
```

Схема, хост и путь должны точно совпадать у поставщика и в Yahont.
Форма управления приложением запрашивает client ID и client secret OAuth;
она не запрашивает токен доступа отдельного пользователя.

> [!NOTE]
>
> При самостоятельном размещении Yahont хост callback берётся из `WEB_DOMAIN`.
> Перед подключением пользователей убедитесь, что эта настройка использует публичный домен,
> зарегистрированный у поставщика.

> [accordion] Slack
>
> Создайте приложение Slack и добавьте redirect URI Yahont в **OAuth & Permissions**.
> Добавьте следующие **User Token Scopes**:
>
> ```text theme={null}
> channels:history
> channels:read
> chat:write
> files:write
> groups:history
> groups:read
> im:history
> im:read
> im:write
> search:read
> users:read
> ```
>
> Craft действует с токеном пользователя; пользователь-бот не нужен.
> Скопируйте Client ID и Client Secret из основной информации приложения Slack.

> [accordion] Google Calendar
>
> В Google Cloud Console создайте или выберите проект, включите **Google Calendar API**,
> настройте экран согласия OAuth и создайте идентификатор клиента OAuth 2.0 типа **Web application**.
> Добавьте redirect URI Yahont в **Authorized redirect URIs**. Craft запрашивает полный доступ к Google Calendar.

> [accordion] Google Drive
>
> В Google Cloud Console включите **Google Drive API** и **Google Docs API**,
> настройте экран согласия OAuth и создайте клиент OAuth 2.0 типа Web application с redirect URI Yahont.
> Craft запрашивает полную область Drive, чтобы читать, создавать, изменять и удалять файлы;
> эти операции внутри Craft регулируются политиками действий.

> [accordion] Gmail
>
> В Google Cloud Console включите **Gmail API**,
> настройте экран согласия OAuth и создайте клиент OAuth 2.0 типа Web application с redirect URI Yahont.
> Craft запрашивает `gmail.modify`, что охватывает чтение, метки, черновики, корзину и отправку,
> но не окончательное удаление сообщений.

> [accordion] Linear
>
> В Linear откройте **Settings → API → OAuth applications**,
> создайте приложение OAuth и добавьте redirect URI Yahont в его callback URL.
> Craft запрашивает доступ на чтение и запись от имени пользователя для задач, проектов и комментариев.

> [accordion] GitHub
>
> В GitHub откройте **Settings → Developer settings → OAuth Apps**,
> создайте OAuth App и укажите redirect URI Yahont как её authorization callback URL. Craft запрашивает `repo`,
> `read:org` и `read:user`; область `repo` включает репозитории, к которым есть доступ у подключающегося пользователя,
> в том числе приватные.

> [accordion] HubSpot
>
> В аккаунте разработчика HubSpot создайте приложение и добавьте redirect URI Yahont на его вкладке **Auth**.
> Настройте доступ на чтение для владельцев, контактов, компаний и сделок. Области записи для контактов,
> компаний и сделок необязательны, чтобы можно было подключать аккаунты HubSpot только для чтения.

> [accordion] Notion
>
> Создайте **публичную** интеграцию в настройках интеграций 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 → Приложения**. Проверьте чтение и характерную запись,
убедитесь, что карточка одобрения понятна, и проверьте результат во внешнем сервисе.

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

Встроенные приложения определяют каталог узнаваемых действий. У каждого действия одна политика на уровне организации:

| Политика | Поведение во время работы | Типичное использование |
| - | - | - |
| **Автоодобрение** | Craft выполняет действие, не останавливаясь для пользователя. | Узкие безопасные операции чтения и неважная подготовка. |
| **Спрашивать** | Craft останавливается перед запросом и показывает пользователю карточку одобрения. | Отправка, создание, изменение, широкое чтение и другие изменения. |
| **Запрещать** | Прокси блокирует действие. Пользователь не может это переопределить. | Разрушительные, неподдерживаемые или запрещённые операции. |

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

Основной переключатель разрешений применяет **Автоодобрение** или **Спрашивать** ко всем действиям.
Откройте **Расширенные**, чтобы создать смешанную политику или выбрать **Запрещать** для отдельных действий.

> [!NOTE]
>
> Если один исходящий запрос соответствует нескольким действиям, побеждает самая строгая подходящая политика:
> **Запрещать**, затем **Спрашивать**, затем **Автоодобрение**. Запрос к встроенному приложению,
> не соответствующий действию из каталога, обрабатывается как **Спрашивать**.

Решение **Одобрить на сессию** внутри сессии применяется только к подходящим действиям в этой сессии.
Оно не меняет политику администратора и не может отменить «Запрещать».

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

[Запланированная задача](https://docs.yahont.ai/overview/core_features/craft_scheduled_tasks.md) выполняется без присутствия пользователя.
Её владелец может выбрать нужные приложения в разделе **Заранее одобренные приложения**.
Для запущенных сессий этой задачи выбор позволяет действиям «Спрашивать» всего приложения выполняться без одобрения в
реальном времени.

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

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

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

| Поле | Назначение |
| - | - |
| **Название и описание** | Определяет приложение для пользователей и поясняет, когда его следует использовать. |
| **Шаблоны URL источника** | Ограничивает, какие исходящие URL запросов относятся к приложению. |
| **Шаблон учётных данных заголовка** | Определяет заголовки, которые подставляет прокси, с заполнителями вроде `{api_key}`. |
| **Учётные данные организации** | Задаёт значения заполнителей, общие для всех пользователей. Значения, которые не заданы, каждый пользователь вводит сам. |
| **Набор** | Содержит инструкции `SKILL.md`, примеры, скрипты и вспомогательные файлы для вызова API. |

Например:

| Настройка | Значение |
| - | - |
| Шаблон URL источника | `https://api.example.com/v1/*` |
| Заголовок | `Authorization` |
| Значение заголовка | `Bearer {api_key}` |
| Учётные данные организации | `api_key` = общий сервисный токен или оставьте пустым, чтобы пользователи вводили свои |

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

В пользовательских приложениях используются глобы URL. Каждый шаблон должен начинаться с `http://` или `https://`,
а хост должен быть буквальным. Подстановочные знаки разрешены только после хоста.

```text theme={null}
# Recommended: one HTTPS host and a narrow path
https://api.example.com/v1/reports/*

# Too broad: every path on the host
https://api.example.com/*

# Invalid: wildcard in the host
https://*.example.com/*
```

> [!WARNING]
>
> Пользовательские приложения нельзя использовать для доступа к частным, loopback, link-local,
> облачным метаданным и другим непубличным сетевым адресам. Прокси песочницы блокирует внутренние адреса,
> даже если шаблон URL их включает. Если Craft должен вызывать пользовательский сервис,
> откройте только намеренно защищённую общедоступную маршрутизируемую конечную точку HTTPS.

Избегайте пересекающихся шаблонов URL между приложениями. Когда один и тот же URL заявлен несколькими приложениями,
первым выбирается приложение с наименьшим ID — обычно созданное раньше всех.
Отключённое приложение всё равно может занять совпадение до проверки доступности учётных данных,
поэтому не полагайтесь на включение или отключение для разрешения пересечений шаблонов.

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

В значении заголовка записывайте каждые учётные данные как именованный заполнитель:

```text theme={null}
Authorization: Bearer {api_key}
X-Workspace-ID: {workspace_id}
```

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

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

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

Набор использует ту же структуру и правила проверки, что и пользовательский навык:

```text theme={null}
example-api.zip
├── SKILL.md
├── examples/
│   └── request.json
└── scripts/
    └── example_api.py
```

Имя ZIP-файла становится slug приложения.
Поместите корректный `SKILL.md` в корень архива или прямо внутрь одной внешней папки и проверьте каждый включённый файл.
Если используется внешняя папка, держите все файлы приложения внутри неё. По умолчанию лимиты:
25 МБ на распакованный файл и 100 МБ на весь набор. Формат набора и контрольный список проверки см.
в разделе [Управление навыками Craft](https://docs.yahont.ai/admins/managing_features/craft_skills.md#prepare-a-custom-skill).

> [!WARNING]
>
> У пользовательских приложений нет каталога действий. Для подключённого пользовательского приложения каждый запрос,
> соответствующий шаблону URL источника, считается неуточнённым действием **Спрашивать**.
> Администраторы не могут автоматически одобрять или запрещать отдельные операции пользовательского приложения.
> Отключите приложение, чтобы прекратить его использование, и будьте особенно осторожны,
> когда пользователи заранее одобряют его для запланированной задачи.

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

| Действие | Результат |
| - | - |
| **Изменить** | Обновляет политики или, если приложением управляет администратор, название, учётные данные OAuth, шаблоны URL, заголовки, учётные данные или набор. |
| **Отключить** | Скрывает приложение от пользователей и прекращает подстановку учётных данных, сохраняя конфигурацию и подключения пользователей. |
| **Включить** | Снова делает приложение доступным. Существующие разрешения пользователей используются повторно, если они остаются действительными. |
| **Удалить** | Безвозвратно удаляет конфигурацию приложения, записи учётных данных пользователей, политики и ссылки на предварительное одобрение запланированных задач. |

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

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

> [accordion] Не удаётся подключить встроенное приложение
>
> Проверьте client ID и secret OAuth, точный redirect URI,
> включённые возможности API или интеграции и необходимые области. Убедитесь,
> что экран согласия поставщика не ограничен одобренными тестовыми пользователями или участниками рабочего
> пространства.

> [accordion] Включённое приложение не отображается пользователям
>
> Убедитесь, что на его карточке указано **Включено** и у пользователя есть доступ к Craft.
> Обновите страницу приложений. Для пользовательского приложения убедитесь,
> что набор и конфигурация сохранены успешно.

> [accordion] Пользователь успешно подключился, но действие заблокировано
>
> Проверьте политику администратора для действия и области или возможности, предоставленные внешним аккаунтом.
> Политику «Запрещать» переопределить нельзя. Запрос «Спрашивать» также может завершиться ошибкой,
> если пользователь отклонит его или срок одобрения истечёт.

> [accordion] Пользовательское приложение запрашивает подтверждение для каждого запроса
>
> Так и должно быть.
> Пользовательские приложения используют одно синтезированное действие «Спрашивать» для каждого запроса,
> соответствующего их шаблонам URL. Они пока не поддерживают политики для отдельных действий.

> [accordion] Пользовательское приложение обращается не к тому сервису или использует не те учётные данные
>
> Проверьте пересекающиеся шаблоны URL. Делайте каждый хост и путь как можно более конкретными.
> Побеждает приложение с наименьшим ID, когда несколько приложений соответствуют одному URL,
> в том числе когда это первое приложение отключено.

> [accordion] Запланированная задача ожидает одобрения
>
> Убедитесь,
> что владелец задачи по-прежнему подключён к приложению и выбрал его в разделе **Заранее одобренные приложения**.
> Затем проверьте наличие политики «Запрещать» или другого приложения, чем ожидалось в запросе.
> Исправьте задачу и используйте **Запустить сейчас**; заблокированный запуск не возобновляется автоматически.

> [card] [Приложения для пользователей](https://docs.yahont.ai/overview/core_features/craft_apps.md)
>
> Покажите пользователям, как подключать аккаунты, направлять Craft и проверять одобрения.

> [card] [Архитектура Craft](https://docs.yahont.ai/security/architecture/craft.md)
>
> Изучите правила исходящего трафика, внедрение учётных данных и применение одобрений.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.