---
author: OOMOL
author_url: https://oomol.com/ru/about/
title: Руководство по OOMOL Connector SaaS
description: Позвольте SaaS-продукту подключать сторонние аккаунты конечных
  пользователей и выполнять действия Connector из backend.
lang: ru
canonical_url: https://oomol.com/ru/docs/connector-saas/
markdown_url: https://oomol.com/ru/docs/connector-saas.md
---

# Руководство по OOMOL Connector SaaS

OOMOL Connector SaaS — это слой подключения аккаунтов для SaaS-продуктов. Используйте его, когда каждому конечному пользователю нужно подключить свой аккаунт Gmail, Slack, Notion или другой сторонний аккаунт, а вашему backend нужно выполнять действия Connector после авторизации. OOMOL Console управляет проектами, provider configs, API-ключами и записями подключений; ваш backend создаёт ссылки авторизации, обрабатывает callbacks, выбирает аккаунты и запускает вызовы действий.

Полная интеграция состоит из двух частей: настройте проект и сервис в OOMOL Console, затем backend создаёт ссылки авторизации, обрабатывает callbacks, выбирает аккаунты и выполняет actions.

Основные темы:

- Какие ресурсы администратор готовит в OOMOL Console.
- Какие IDs и secrets должен хранить backend.
- Что делают frontend и backend, когда конечный пользователь подключает аккаунт.
- Как выбрать подключённый аккаунт и выполнить action.
- Какие страницы Console, статусы, logs и views использования помогают при troubleshooting.

## Модель интеграции

SaaS-интеграция имеет фазу настройки и фазу runtime.

Фаза настройки происходит в OOMOL Console. Она готовит project, provider config и backend API key, а также записывает IDs и secrets, необходимые во время runtime. Конечные пользователи не участвуют в этих шагах.

Фаза runtime происходит в backend вашего продукта. Она представляет ваш SaaS project при создании account links, чтении статуса connection request и выполнении actions. Runtime requests включают project API key:

```http
authorization: Bearer <project-api-key>
```

Project API key остаётся на вашем backend. Конечные пользователи используют только UI вашего продукта или открывают OAuth authorization URL, возвращённый Connector.

## Данные для хранения

Типичная интеграция хранит эти значения:

| Значение | Где хранить | Почему это важно |
| --- | --- | --- |
| `projectId` | Backend configuration или database | Идентифицирует один SaaS project. |
| `providerConfigId` | Backend configuration или database | Идентифицирует provider config внутри project. Runtime calls должны предпочитать его. |
| `projectApiKey` | Backend secret manager | Аутентифицирует Connector runtime calls. Открытый ключ возвращается только один раз. |
| `userId` | Database вашего продукта | ID конечного пользователя в вашем продукте. Connector хранит его как `externalUserId`. |
| `connectedAccountId` или `alias` | Database вашего продукта | Выбирает подключённый аккаунт конечного пользователя при выполнении actions. |

Если пользователи могут подключать несколько аккаунтов Gmail, храните `connectedAccountId` или `alias` каждого аккаунта, чтобы runtime calls не зависели от выбора по умолчанию «последнего аккаунта».

## Шаг 1: создайте project

Project — это граница изоляции SaaS-интеграции. Он изолирует provider configs, API keys, connected accounts, execution logs и usage.

В OOMOL Console:

![Страница Projects в OOMOL Console с пунктом Create project в основной панели](/img/docs/connector-saas/en/project-list.webp)

1. Откройте **Projects** в левой боковой панели.
2. Нажмите **Create project**.
3. Заполните имя project.
4. После создания откройте project и сохраните project ID как `PROJECT_ID`.

![Диалог Create project с полем Project name и кнопкой Create](/img/docs/connector-saas/en/create-project-dialog.webp)

Страница project содержит пункты **Provider configs**, **API Keys**, **Connected accounts**, **Execution logs** и **Usage**. Остальная настройка выполняется внутри этого project.

Имя project отображается на странице входа OAuth-авторизации. Production-интеграции должны использовать product name, который конечные пользователи узнают, чтобы цель авторизации была понятной.

## Шаг 2: создайте provider config

Provider config определяет, как этот project подключается к одному сервису Connector. Runtime requests передают его как `providerConfigId`. Для Gmail OAuth:

![Страница provider configs проекта с кнопкой Create provider config](/img/docs/connector-saas/en/service-configs-page.webp)

1. Откройте **Provider configs** в боковой панели project.
2. Нажмите **Create provider config**.
3. Выберите или заполните эти поля.
4. Нажмите **Create**.

![Диалог Create provider config с полями service, auth type, config identifier, display name и client config source](/img/docs/connector-saas/en/create-service-config-dialog.webp)

| Поле | Пример Gmail | Примечания |
| --- | --- | --- |
| Service | `Gmail` | Сервис Connector для подключения. |
| Auth type | `OAuth2` | Gmail использует OAuth2 authorization. |
| Config slug | `gmail` | Читаемый identifier, который backend использует для этой config. Если в одном project несколько configs для одного service, используйте имена вроде `gmail-work` или `gmail-personal`. |
| Display name | `Gmail` | Имя, показываемое конечным пользователям на странице входа авторизации. |
| Client config source | `System Client` | Использует OAuth client, предоставленный OOMOL. |

После создания сохраните provider config ID как `PROVIDER_CONFIG_ID`. Backend должен явно передавать его при создании authorization links и выполнении actions.

Когда каждый SaaS project использует собственный OAuth client, измените **Client config source** на custom client и предоставьте соответствующие `clientId` и `clientSecret`.

При custom OAuth client настройте Connector callback URL в консоли provider. OOMOL Console или ваша deployment configuration предоставляет этот URL; конечным пользователям он не нужен.

Для сервиса с API key выберите соответствующий тип API-key auth. Когда конечный пользователь подключает аккаунт, backend отправляет пользовательский provider API key в Connector для хранения.

## Шаг 3: создайте project API key

Project API key предназначен только для backend. Не отправляйте его в browsers, mobile clients или устройства конечных пользователей.

На странице project:

1. Откройте **API Keys** в боковой панели project.
2. Нажмите **Create API Key**.
3. Заполните имя key. Используйте имя, упрощающее rotation и troubleshooting, например `production server key` или `staging server key`.
4. Нажмите **Create**.
5. Скопируйте открытый ключ из одноразового диалога и сохраните его как `PROJECT_API_KEY`.

![Одноразовый диалог ключа с предупреждением, что полный ключ больше не будет показан](/img/docs/connector-saas/en/api-key-once-dialog.webp)

Открытый ключ возвращается только один раз. В дальнейшем списки показывают только префикс key, время создания, время недавнего использования и похожие metadata. Если key утёк, отзовите его в Console и создайте новый.

## Шаг 4: дайте конечному пользователю подключить аккаунт

Теперь переходите к product runtime flow. Предположим, в вашем продукте есть пользователь с ID `customer-1`, который хочет подключить Gmail.

Backend создаёт OAuth authorization link:

```bash
CONNECTOR=https://connector.oomol.com
PROJECT_API_KEY=oo_proj_...

curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "alias": "work",
    "returnUri": "https://app.example/connector/callback"
  }'
```

Ответ содержит `data.authorizationUrl`, URL входа авторизации, принадлежащий Connector. Перенаправьте конечного пользователя на этот URL.

Эта страница кратко показывает display title project, icon project и display name provider config, затем перенаправляет на настоящую OAuth-страницу provider. После авторизации пользователя provider вызывает Connector callback, а Connector перенаправляет на предоставленный `returnUri`.

При успехе `returnUri` получает query parameters вида:

```text
status=success
service=gmail
providerConfigId=pc-1
externalUserId=customer-1
connectedAccountId=ca-1
```

Frontend может отправить `connectedAccountId` в backend для хранения. Backend также может запросить status connection request:

```bash
curl -sS "$CONNECTOR/v1/saas/connection-requests/$REQUEST_ID" \
  -H "authorization: Bearer $PROJECT_API_KEY"
```

Если пользователь отменяет или provider возвращает ошибку, `returnUri` получает:

```text
status=error
code=<connector-error-code>
message=<human-readable-message>
```

`returnUri` должен использовать `http` или `https`. OAuth links по умолчанию истекают через 10 минут.

## Шаг 5: выполните action

После подключения аккаунта backend может выполнять actions с сохранённым account selector.

```bash
curl -sS -X POST "$CONNECTOR/v1/saas/actions/gmail.send_email" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -H "x-request-id: req-saas-action-1" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "connectedAccountId": "ca-1",
    "input": {
      "to": "someone@example.com",
      "subject": "Hello",
      "body": "Hello from My SaaS"
    }
  }'
```

Правила:

- Передавайте ровно одно из `providerConfigId` или `service`. Production-интеграции должны предпочитать `providerConfigId`.
- Передавайте не более одного из `connectedAccountId` или `alias`. Production-интеграции должны явно передавать одно из них.
- Если account selector отсутствует, Connector выбирает последний active connected account в рамках того же `projectId + providerConfigId + userId`.
- Service prefix в action ID должен соответствовать service provider config. Например, `gmail.send_email` должен использовать Gmail provider config.

Успешный ответ включает `executionId`, `actionId` и action output. Сохраняйте `executionId` в собственных operation logs для поддержки и troubleshooting.

## Шаг 6: управляйте подключениями пользователей

Продуктам обычно нужно показывать пользователям, какие аккаунты они подключили. Рекомендуемый подход — после успешного callback сохранять `connectedAccountId`, `alias`, `service`, `providerConfigId` и ваш собственный `userId` в database продукта, а затем отображать список аккаунтов из этих данных.

Чтобы проверить состояние на стороне Connector, используйте **Connected accounts** в OOMOL Console для просмотра подключённых аккаунтов текущего project.

Поле `available` показывает, может ли аккаунт сейчас выполнять actions. Оно равно `true` только когда provider config активна, connected account активен, underlying app активен и credential существует.

Если продукт позволяет пользователям переименовывать аккаунты, сначала обновите display name в database продукта. Когда администратору нужно проверить состояние на стороне Connector, используйте Console для просмотра соответствующего account.

Когда пользователь отключает аккаунт, backend продукта должен выполнить disconnect flow и обновить database продукта. Администраторы могут использовать Console, чтобы проверить, доступен ли account.

Disconnect сохраняет запись connected account, но удаляет underlying credential. Исторические logs всё ещё могут ссылаться на account; будущие actions не смогут его использовать.

## Шаг 7: устранение неполадок и эксплуатация

При troubleshooting действия пользователя откройте **Execution logs** в OOMOL Console. Частые filters: `providerConfigId`, `userId`, `appId`, `status=success|error` и `action`.

При troubleshooting сначала сузьте вид по service или provider config. Если operation logs хранят `executionId`, используйте его, чтобы связать одну product-side operation с Connector-side log.

Для эксплуатации используйте **Usage**, чтобы смотреть daily usage trends и usage, сгруппированный по service. Частые окна: 7, 30 или 90 дней.

`days` поддерживает только `7`, `30` или `90`.

## Что backend вызывает во время runtime

Для потока Gmail OAuth в этом руководстве backend выполняет три задачи:

- Создаёт authorization link и отправляет пользователя на вход авторизации Connector.
- Подтверждает connection request после callback, затем сохраняет `connectedAccountId`.
- Выполняет actions с сохранённым account, когда пользователь запускает product feature.

Предпочитайте OOMOL Console для настройки и операций: создания projects, provider configs, project API keys, просмотра connected accounts, чтения execution logs и проверки usage.

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

Когда connection account или execution action завершается ошибкой, проверяйте в таком порядке:

1. Подтвердите, что backend использует `PROJECT_API_KEY` текущего project и key не раскрыт browsers или mobile clients.
2. Подтвердите, что запрос использует `providerConfigId` созданной provider config.
3. Подтвердите, что тот же user не переиспользует существующий `alias`.
4. Откройте **Connected accounts** в Console и проверьте, доступен ли account.
5. Откройте **Execution logs** в Console и отфильтруйте по provider config, user ID или `executionId`.