SaaS Proxy로 공급자 API 호출하기

Connector 작업으로 제공되지 않는 공급자 엔드포인트가 필요하면 SaaS Proxy를 사용하세요. 백엔드가 경로, 메서드, 매개변수를 전달하면 Connector가 사용자의 연결된 계정을 선택하고 인증 정보를 추가합니다. 공급자가 proxy를 지원해야 하며 계정의 기존 권한이 적용됩니다.

연결된 계정 준비

먼저 Connector for SaaS 가이드를 완료하세요. Project API key를 백엔드에 보관하고 검증된 사용자와 계정의 연결 관계를 저장합니다. 개인 키나 공급자 token 대신 oo_proj_… 형식의 Project key를 사용하세요. userId와 계정은 인증된 제품 세션에서 결정하고 브라우저가 보낸 임의의 계정 ID를 신뢰하지 마세요.

HTTP로 호출

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

아래 읽기 전용 Gmail 예제는 연결된 계정의 프로필을 가져옵니다. 설정 ID와 계정 ID를 저장된 값으로 바꾸고 프로필 읽기 권한을 확인하세요. 외부 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로 호출

ProjectConnector.proxy가 포함된 @oomol-lab/connector 릴리스를 사용하세요. 설치된 버전에 이 메서드가 없으면 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가 성공해도 data.status에 공급자의 2xx 이외 상태가 들어갈 수 있습니다. SDK에서는 result.status와 공급자 응답 본문을 확인합니다. Connector 실패는 SDK에서 ConnectorError로 발생합니다. 잘못된 Project API key는 HTTP 401과 일반 텍스트 Unauthorized를 반환할 수 있으므로 모든 오류를 JSON으로 가정하지 마세요.

제한 및 문제 해결

• Proxy는 파싱한 JSON 또는 텍스트를 반환하며 스트리밍이나 바이너리 전송 인터페이스가 아닙니다. 기본 공급자 타임아웃은 30초, 응답 한도는 4 MiB이며 공급자별로 달라질 수 있습니다.

• Proxy는 OAuth 권한을 추가하지 않습니다. scope가 부족하면 설정을 확인하고 사용자에게 필요한 권한으로 다시 인증하도록 요청하세요. 공급자가 허용한 출처만 사용할 수 있습니다.

• provider_config_not_found와 multiple_provider_configs_found는 설정 선택 문제, proxy_not_supported는 미지원 공급자를 나타냅니다. proxy_upstream_timeout 또는 proxy_response_too_large가 발생하면 가능한 경우 요청이나 응답 범위를 줄이세요.

• 타임아웃이 공급자의 쓰기 실패를 의미하지는 않습니다. 중복 효과가 발생할 수 있는 작업은 자동 재시도를 끄세요. SDK 예제는 retries를 0으로 설정합니다. 요청 ID와 제공된 HTTP meta.executionId를 기록하고 OOMOL Console의 프로젝트 실행 로그를 확인하세요.

ProjectConnector 계정 연결도 참고하세요.