---
title: ProjectConnector로 최종 사용자 계정 연결하기
description: TypeScript 백엔드에서 ProjectConnector를 사용하여 SaaS 사용자의 계정을 연결하고 해당 사용자를
  대신해 작업을 실행하세요.
lang: ko
canonical_url: https://oomol.com/ko/docs/project-connector/
markdown_url: https://oomol.com/ko/docs/project-connector.md
---

# ProjectConnector로 최종 사용자 계정 연결하기

제품의 모든 사용자가 각자의 제공자 계정을 연결해야 할 때 `ProjectConnector`을 사용하세요. 백엔드는 `externalUserId`로 각 사용자를 식별하고, 인증 링크를 생성하며, 연결된 계정 ID를 저장하고, 해당 사용자를 위해 작업을 실행합니다.

이 경로는 `oo_proj_…` 형태의 프로젝트 API 키를 사용합니다. `Connector`에서 사용하는 개인 `api_…` 키와는 별개입니다.

## 프로젝트 준비하기

런타임 흐름을 작성하기 전에 OOMOL Console에서 다음 리소스를 생성하세요:

1. Connector 프로젝트.
2. 사용자가 연결할 수 있는 각 서비스에 대한 제공자 구성.
3. 백엔드 시크릿 관리자에 저장된 프로젝트 API 키.

[Connector for SaaS 가이드](/ko/docs/connector-saas/)에서 Console 설정과 이에 대응하는 REST 요청을 다룹니다.

## 설치 및 초기화

```sh
npm install @oomol-lab/connector
```

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

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

## OAuth 인증 요청 생성하기

자체 사용자 데이터베이스의 안정적인 ID를 `externalUserId`로 사용하세요:

```ts
const request = await project.connect.oauth("user_42", {
  service: "gmail",
  connectionName: "work",
  returnUri: "https://app.example.com/connected",
});

redirectUserTo(request.authorizationUrl);
```

사용자가 인증한 후 요청이 최종 상태에 도달할 때까지 기다리세요:

```ts
const connected = await project.waitForConnection(request);

if (connected.status === "connected") {
  saveConnectedAccountId(connected.connectedAccountId);
}
```

`project.connect.oauth`은 사용자를 기다리는 인증 요청을 반환합니다. 인증이 성공한 후에만 `waitForConnection`가 요청 결과에서 `connectedAccountId`을 반환합니다.

API 키 및 사용자 지정 자격 증명 제공자의 경우 `connect.apiKey` 또는 `connect.customCredential`를 사용하세요. 이 메서드들은 자격 증명을 검증하고 연결된 계정을 동기적으로 반환합니다.

## 한 사용자를 위해 실행하기

```ts
const result = await project.execute(
  "user_42",
  "gmail.search_threads",
  { query: "is:unread" },
  { connectedAccountId: "ca-1" },
);
```

`connectedAccountId`이 있으면 전달하세요. 특정 계정 하나를 선택하고 최신 활성 계정에 의존하지 않도록 합니다. 제품에서 안정적인 별칭을 사용하는 경우에는 `connectionName`을 사용할 수 있습니다.

여러 작업이 동일한 요청이나 작업에 속할 때 `forUser`로 사용자를 한 번 바인딩하세요:

Slack 예제에는 이 사용자의 기존 "work" 연결이 필요합니다. 백엔드에 저장한 해당 Slack 계정의 연결 이름을 사용하세요. forUser는 사용자만 지정하며 계정 선택자는 execute 옵션으로 전달합니다.

```ts
const user = project.forUser("user_42");
await user.execute(
  "slack.post_message",
  { channel: "#general", text: "shipped" },
  { connectionName: "work" },
);
```

## 제품 경계를 명확히 유지하기

제품은 자체 사용자를 인증하고 사용자가 사용할 수 있는 제공자와 작업을 제어합니다. 프로젝트 API 키는 백엔드에 보관하고, 일관된 `externalUserId`을 전달하며, 반환된 계정 선택자를 해당 제품 사용자 옆에 저장하세요.

인증 요청 및 연결된 계정 수명 주기 필드, 정확한 작업 유형, 오류, 재시도, 대기 옵션, 그리고 전체 `ProjectConnector` API는 [TypeScript SDK 레퍼런스](/ko/docs/connector-sdk/)를 참조하세요.