Вызов API провайдеров через SaaS Proxy

Используйте SaaS Proxy для endpoint, который ещё не представлен готовой операцией Connector. Ваш backend задаёт путь, метод и параметры, а Connector выбирает подключённый аккаунт пользователя и добавляет учётные данные. Провайдер должен поддерживать proxy; действуют существующие разрешения аккаунта.

Подготовка аккаунта

Сначала выполните руководство Connector for SaaS. Храните Project API key на backend и сохраняйте проверенную связь пользователя с аккаунтом. Используйте ключ проекта вида oo_proj_…, а не личный ключ или token провайдера. Определяйте userId и аккаунт по аутентифицированной сессии продукта, не доверяя произвольным ID из браузера.

Вызов через HTTP

POST https://connector.oomol.com/v1/saas/proxy/{service}
Authorization: Bearer <project-api-key>
Content-Type: application/json

Этот пример Gmail только читает профиль подключённого аккаунта. Замените ID конфигурации и аккаунта значениями из backend. Аккаунту нужно разрешение на чтение профиля. Внешний HTTP-метод всегда POST, а метод провайдера задаётся внутри request.

export PROJECT_API_KEY='oo_proj_...'
export PROVIDER_CONFIG_ID='<gmail-provider-config-id>'
export CONNECTED_ACCOUNT_ID='<connected-account-id>'

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/proxy/gmail' \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: req-saas-proxy-1' \
  --data @- <<JSON
{
  "providerConfigId": "$PROVIDER_CONFIG_ID",
  "userId": "customer-1",
  "connectedAccountId": "$CONNECTED_ACCOUNT_ID",
  "request": {
    "endpoint": "/users/me/profile",
    "method": "GET"
  }
}
JSON

Поля запроса

Вызов через ProjectConnector

Используйте выпуск @oomol-lab/connector с ProjectConnector.proxy. Если установленная версия не содержит этот метод, используйте HTTP-пример. SDK преобразует externalUserId и connectionName в userId и alias. connectedAccountId имеет приоритет над connectionName. Параметр типа описывает ожидаемые данные, но не проверяет их во время выполнения.

npm install @oomol-lab/connector

import { ProjectConnector } from "@oomol-lab/connector";

const project = new ProjectConnector({
  apiKey: process.env.PROJECT_API_KEY!,
});

const result = await project.proxy<{ emailAddress: string }>(
  "customer-1",
  "gmail",
  { endpoint: "/users/me/profile", method: "GET" },
  {
    providerConfigId: process.env.PROVIDER_CONFIG_ID!,
    connectedAccountId: process.env.CONNECTED_ACCOUNT_ID!,
    retries: 0,
  },
);

if (result.status < 200 || result.status >= 300) {
  throw new Error(`Provider returned HTTP ${result.status}`);
}
console.log(result.data.emailAddress);

Для нескольких вызовов одного пользователя можно привязать его один раз:

const user = project.forUser("customer-1");
const profile = await user.proxy<{ emailAddress: string }>(
  "gmail",
  { endpoint: "/users/me/profile", method: "GET" },
  {
    providerConfigId: process.env.PROVIDER_CONFIG_ID!,
    connectionName: "work",
    retries: 0,
  },
);
if (profile.status < 200 || profile.status >= 300) {
  throw new Error(`Provider returned HTTP ${profile.status}`);
}
console.log(profile.data.emailAddress);

Ответы и обработка ошибок

Ниже показан пример HTTP-конверта. SDK возвращает непосредственно объект data: status, headers и data. При HTTP-вызове сохраняйте meta.executionId для диагностики.

{
  "success": true,
  "message": "OK",
  "data": {
    "status": 200,
    "headers": { "content-type": "application/json" },
    "data": {
      "emailAddress": "user@example.com",
      "messagesTotal": 120,
      "threadsTotal": 80,
      "historyId": "12345"
    }
  },
  "meta": {
    "executionId": "exec-example",
    "service": "gmail",
    "appId": "app-example"
  }
}

Проверяйте оба уровня. Успешный конверт Connector может содержать статус провайдера вне 2xx в data.status; в SDK проверяйте result.status и тело ответа провайдера. Ошибки Connector вызывают ConnectorError. Неверный Project API key может вернуть HTTP 401 с обычным текстом Unauthorized: не считайте все ошибки JSON-ответами.

Ограничения и диагностика

• Proxy возвращает разобранный JSON или текст, а не поток или бинарные данные. По умолчанию тайм-аут провайдера составляет 30 секунд, предел ответа — 4 MiB; провайдер может менять эти ограничения.

• Proxy не добавляет разрешений OAuth. При нехватке scopes проверьте конфигурацию и попросите пользователя повторно предоставить нужные разрешения. Допускаются только источники, разрешённые провайдером.

• provider_config_not_found и multiple_provider_configs_found относятся к выбору конфигурации; proxy_not_supported означает отсутствие поддержки proxy. При proxy_upstream_timeout или proxy_response_too_large по возможности уменьшите объём запроса или ответа.

• Тайм-аут не доказывает, что запись у провайдера не состоялась. Отключайте автоматические повторы для операций с риском дублирования; в SDK-примерах retries равен нулю. Сохраняйте ID запроса и HTTP meta.executionId, если он есть, и проверяйте журнал выполнения проекта в OOMOL Console.

См. также подключение аккаунтов с ProjectConnector.