Руководство по 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:

authorization: Bearer <project-api-key>

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

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

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

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

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

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

В OOMOL Console:

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

Страница 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:

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

После создания сохраните 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.

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

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

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

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

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 вида:

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

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

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

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

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

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

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

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

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.