---
title: Connector for SaaS 使用指南
description: 讓 SaaS 產品為終端使用者連接第三方帳號，並由後端代使用者執行 Connector actions。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/connector-saas/
markdown_url: https://oomol.com/zh-tw/docs/connector-saas.md
---

# Connector for SaaS 使用指南

Connector for SaaS 是給 SaaS 產品使用的使用者帳號連接方案。適合需要讓每個終端使用者連接自己的 Gmail、Slack、Notion 等第三方帳號，並由產品後端在使用者授權後執行 Connector action 的情境。它在 OOMOL Console 中管理 Project、provider configs、API keys 和 connected accounts；你的後端負責建立授權連結、處理回呼、選擇帳號並發起 action 呼叫。

一次完整接入包含兩部分：先在 OOMOL Console 完成專案和服務設定，再由你的後端建立授權連結、處理回呼、選擇帳號並執行 action。

主要內容：

- 管理員需要在 OOMOL Console 裡準備哪些資源。
- 你的後端需要保存哪些 ID 和密鑰。
- 終端使用者連接帳號時，你的前端和後端分別做什麼。
- 使用者連接完成後，如何選擇帳號並執行 action。
- 出問題時應該查哪些狀態。

## 接入模型

SaaS 接入分為設定期和執行期。

設定期在 OOMOL Console 完成，用來準備專案、服務設定和後端 API Key，並記錄執行期所需的 ID 和密鑰。終端使用者不會參與這些步驟。

執行期發生在你的產品後端。它代表你的 SaaS Project 建立帳號授權請求、查詢請求狀態和執行 action，請求需要帶 Project API key：

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

Project API key 只在你的後端使用。終端使用者只會打開你的產品頁面，或打開 Connector 返回的 OAuth 授權連結。

## 你需要保存的資料

一次接入通常需要保存這些值：

| 值 | 保存位置 | 用途 |
| --- | --- | --- |
| `projectId` | 你的後端設定或資料庫 | 標識一個 SaaS 專案。 |
| `providerConfigId` | 你的後端設定或資料庫 | 標識這個專案下的某個服務設定。生產環境推薦執行時都傳它。 |
| `projectApiKey` | 你的後端密鑰管理系統 | 呼叫 Connector 執行期介面。明文只在建立時返回一次。 |
| `userId` | 你的業務資料庫 | 你的產品裡的終端使用者 ID。Connector 會保存為 `externalUserId`。 |
| `connectedAccountId` 或 `alias` | 你的業務資料庫 | 終端使用者連接成功後的帳號選擇器。執行 action 時用它指定帳號。 |

如果你的使用者可以連接多個 Gmail 帳號，保存每個帳號對應的 `connectedAccountId` 或 `alias`，避免執行期只能依賴「最新帳號」預設選擇。

## 第 1 步：建立專案

Project 是 SaaS 接入的隔離單元，會隔離服務設定、API Keys、連接帳號、執行記錄和用量。

在 OOMOL Console 裡操作：

![OOMOL Console 專案頁，頁面中間有建立專案入口](/img/docs/connector-saas/zh-cn/project-list.png)

1. 打開左側「專案」。
2. 點擊「建立專案」。
3. 按表單填寫專案名稱。
4. 建立後進入專案詳情頁，保存專案 ID，後面記為 `PROJECT_ID`。

![建立專案對話方塊，填寫專案名稱後點選建立](/img/docs/connector-saas/zh-cn/create-project-dialog.png)

專案詳情頁左側會出現「服務設定」「API Keys」「連接帳號」「執行記錄」「用量」等入口。後續設定都在該專案內完成。

專案名稱會顯示在 OAuth 授權入口頁。生產環境建議使用終端使用者能識別的產品名稱，明確授權對象。

## 第 2 步：建立服務設定

服務設定（後端參數裡的 `providerConfig`）定義該專案如何連接某個 Connector 服務。以 Gmail OAuth 為例：

![專案詳情頁的服務設定頁面，右上角有建立服務設定按鈕](/img/docs/connector-saas/zh-cn/service-configs-page.png)

1. 在專案詳情頁打開左側「服務設定」。
2. 點擊右上角「建立服務設定」。
3. 按表單選擇或填寫下面這些欄位。
4. 點擊「建立」。

![建立服務設定對話方塊，包含服務、授權型別、設定識別碼、顯示名稱和 Client 設定來源](/img/docs/connector-saas/zh-cn/create-service-config-dialog.png)

| 欄位 | Gmail 範例 | 說明 |
| --- | --- | --- |
| 服務 | `Gmail` | 要接入的 Connector 服務。 |
| 授權類型 | `OAuth2` | Gmail 使用 OAuth2 授權。 |
| 設定標識 | `gmail` | 你的後端識別該設定時使用。一個專案下同一個服務有多個設定時，建議用 `gmail-work`、`gmail-personal` 這類可讀標識。 |
| 顯示名稱 | `Gmail` | 授權入口頁展示給終端使用者看的名稱。 |
| Client 設定來源 | `系统 Client` | 使用 OOMOL 提供的 OAuth client。 |

建立完成後保存 provider config ID，後面記為 `PROVIDER_CONFIG_ID`。後端建立授權連結和執行 action 時都推薦顯式傳它。

每個 SaaS 專案需要使用自己的 OAuth client 時，把「Client 設定來源」改成自訂 Client，並填寫對應的 `clientId` 和 `clientSecret`。

使用自訂 OAuth client 時，需要在 provider 後台設定 Connector 的回呼地址。OOMOL Console 或部署設定會提供這個僅供管理員使用的地址。

接入 API key 類型服務時，在「授權類型」裡選擇對應的 API key 模式。終端使用者連接帳號時，你的後端把使用者提供的服務方 API key 交給 Connector 保存。

## 第 3 步：建立 API Key

Project API key 只給你的後端使用，不能發送到瀏覽器、行動端或終端使用者裝置。

在專案詳情頁裡操作：

1. 打開左側「API Keys」。
2. 點擊「建立 API Key」。
3. 填寫 Key 名稱。建議寫清用途和環境，例如 `production server key` 或 `staging server key`，方便後續輪換和排查。
4. 點擊「建立」。
5. 複製一次性彈窗裡的明文 key，後面記為 `PROJECT_API_KEY`。

![一次性 Key 對話方塊，提示關閉後不會再顯示完整 Key](/img/docs/connector-saas/zh-cn/api-key-once-dialog.png)

明文 key 只返回一次。之後列表裡只會看到 key 前綴、建立時間和最近使用時間等資訊。key 洩露時，在 Console 裡吊銷並重新建立。

## 第 4 步：讓終端使用者連接帳號

現在進入產品執行時流程。假設你的產品裡有一個使用者 ID 是 `customer-1`，他要連接自己的 Gmail 帳號。

你的後端建立 OAuth 授權連結：

```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.id` 和 `data.authorizationUrl`。跳轉前，可信後端應保存 `data.id`，並記錄該請求預期的 Project、服務設定和產品使用者；隨後再把使用者跳轉到 Connector 提供的 `data.authorizationUrl`。

該頁面會短暫展示專案的展示名稱、圖示和服務設定的顯示名稱，然後跳轉到真實 provider OAuth 頁面。使用者授權完成後，provider 會回呼 Connector，Connector 再重定向到你傳入的 `returnUri`。

成功時，`returnUri` 會帶上這些 query 參數：

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

這些 query 參數只用於展示跳轉結果，不應作為帳號綁定依據。不要直接保存瀏覽器傳回的 `connectedAccountId`。後端應使用 Project API key 查詢之前保存的連接請求；API 路徑沿用 `connection-requests` 命名：

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

僅當返回值中的 `data.status` 為 `connected`，並且 `projectId`、`providerConfigId`、`externalUserId` 都與後端為該請求保存的值一致時，才持久化 `data.connectedAccountId`。`failed` 與 `expired` 都是終態，不應建立帳號綁定。

如果使用者取消授權或 provider 返回錯誤，`returnUri` 會帶上：

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

`returnUri` 只允許 `http` 或 `https`。OAuth link 預設 10 分鐘過期。

## 第 5 步：執行 action

使用者連接成功後，後端即可用保存的帳號執行 action。

```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` 二選一。生產環境推薦傳 `providerConfigId`。
- `connectedAccountId` / `alias` 最多傳一個。生產環境推薦顯式傳其中一個。
- 如果不傳帳號選擇器，Connector 會選擇同一 `projectId + providerConfigId + userId` 下最新的 active connected account。
- Action ID 的 service 前綴必須和 provider config 的 `service` 一致。例如 `gmail.send_email` 必須使用 Gmail provider config。

成功回應會返回 `executionId`、`actionId` 和 action 輸出。可將 `executionId` 保存到自己的操作日誌中，方便後續排查。

## 第 6 步：管理使用者連接

產品通常需要展示使用者已連接的帳號。推薦做法是：連接成功後，把回呼裡的 `connectedAccountId`、`alias`、`service`、`providerConfigId` 和你的 `userId` 一起保存到業務資料庫，並用這些資料渲染帳號列表。

需要校驗 Connector 側即時狀態時，可在 OOMOL Console 的「連接帳號」頁查看當前專案下的 connected accounts。

返回項裡的 `available` 表示該帳號當前是否能執行 action。只有 provider config 未刪除、connected account 是 active、底層 app 是 active 且 credential 存在時才是 `true`。

如果產品允許使用者給帳號改名，建議先在業務資料庫裡更新顯示名；管理員需要核對 Connector 側狀態時，再到 Console 查看對應帳號。

使用者斷開帳號時，建議由產品後端執行斷開流程，並同步更新業務資料庫。管理員排查時可在 Console 查看該帳號是否仍然可用。

Disconnect 會保留 connected account 記錄，但移除底層 credential。歷史日誌仍可關聯到該帳號，後續 action 不能再使用它。

## 第 7 步：排查和營運

排查某個使用者的 action 問題時，在 OOMOL Console 的「執行記錄」裡查看 execution logs。常見過濾條件包括 `providerConfigId`、`userId`、`appId`、`status=success|error` 和 `action`。

排查時至少按服務或服務設定縮小範圍。業務日誌保存了 `executionId` 時，可以用它把產品側的一次操作和 Connector 側日誌對應起來。

營運時可在「用量」裡查看每日用量趨勢，也可以查看按 service 聚合的用量，常用窗口是 7、30 或 90 天。

`days` 只支援 `7`、`30`、`90`。

## 後端執行期要呼叫什麼

這篇指南的 Gmail OAuth 主流程裡，後端需要處理三件事：

- 建立授權連結，把使用者帶到 Connector 授權入口。
- 在回呼後確認授權請求狀態，並保存 `connectedAccountId`。
- 使用者觸發功能時，用保存的帳號執行 action。

建立專案、建立服務設定、建立 API Key、查看連接帳號、執行記錄和用量這些設定或營運動作，優先於 OOMOL Console 完成。

## 排查建議

連接或 action 執行失敗時，按這個順序排查：

1. 確認後端使用的是當前 Project 的 `PROJECT_API_KEY`，並且未放到瀏覽器或行動端。
2. 確認請求裡傳的是當前服務設定對應的 `providerConfigId`。
3. 確認對同一使用者設定了唯一的 `alias`。
4. 在 Console 的「連接帳號」裡查看帳號是否仍然可用。
5. 在 Console 的「執行記錄」裡按服務設定、使用者 ID 或 `executionId` 查詢失敗原因。