---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: Connector for SaaS 使用指南
description: 让 SaaS 产品为终端用户连接第三方账号，并由后端代用户执行 Connector actions。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/connector-saas/
markdown_url: https://oomol.com/zh-cn/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.webp)

1. 打开左侧「项目」。
2. 点击「创建项目」。
3. 按表单填写项目名称。
4. 创建后进入项目详情页，保存项目 ID，后面记为 `PROJECT_ID`。

![创建项目弹窗，填写项目名称后点击创建](/img/docs/connector-saas/zh-cn/create-project-dialog.webp)

项目详情页左侧会出现「服务配置」「API Keys」「连接账号」「执行记录」「用量」等入口。后续配置都在该项目内完成。

项目名称会显示在 OAuth 授权入口页。生产环境建议使用终端用户能识别的产品名称，明确授权对象。

## 第 2 步：创建服务配置

服务配置（后端参数里的 `providerConfig`）定义该项目如何连接某个 Connector 服务。以 Gmail OAuth 为例：

![项目详情页的服务配置页面，右上角有创建服务配置按钮](/img/docs/connector-saas/zh-cn/service-configs-page.webp)

1. 在项目详情页打开左侧「服务配置」。
2. 点击右上角「创建服务配置」。
3. 按表单选择或填写下面这些字段。
4. 点击「创建」。

![创建服务配置弹窗，包含服务、授权类型、配置标识、显示名称和 Client 配置来源](/img/docs/connector-saas/zh-cn/create-service-config-dialog.webp)

| 字段 | 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.webp)

明文 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` 查询失败原因。