---
author: OOMOL
author_url: https://oomol.com/ja/about/
title: OOMOL Connector SaaS ガイド
description: SaaS 製品でエンドユーザーの第三者アカウントを接続し、backend から Connector actions を実行します。
lang: ja
canonical_url: https://oomol.com/ja/docs/connector-saas/
markdown_url: https://oomol.com/ja/docs/connector-saas.md
---

# OOMOL Connector SaaS ガイド

OOMOL Connector SaaS は、SaaS 製品向けのアカウント接続レイヤーです。各エンドユーザーが自分の Gmail、Slack、Notion、またはその他の第三者アカウントを接続し、認可後に backend が Connector actions を実行する必要がある場合に使用します。OOMOL Console は projects、provider configs、API keys、connection records を管理し、backend は authorization links の作成、callbacks の処理、accounts の選択、action calls の開始を行います。

完全な統合は 2 つの部分で構成されます。まず OOMOL Console で project と service を設定し、次に backend が authorization links を作成し、callbacks を処理し、accounts を選択し、actions を実行します。

主な内容:

- 管理者が OOMOL Console で準備する resources。
- backend が保存する必要のある IDs と secrets。
- エンドユーザーが account を接続するときに frontend と backend が行うこと。
- 接続済み account を選択して action を実行する方法。
- トラブルシューティングに役立つ Console pages、statuses、logs、usage views。

## 統合モデル

SaaS 統合には setup phase と runtime phase があります。

setup phase は OOMOL Console で行います。project、provider config、backend API key を準備し、runtime に必要な IDs と secrets を記録します。エンドユーザーはこれらの手順に関与しません。

runtime phase は製品 backend で行います。account links の作成、connection request status の読み取り、actions の実行時に SaaS project を表します。runtime requests には project API key が含まれます。

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

project API key は backend に保持します。エンドユーザーは製品 UI を使うか、Connector が返す OAuth authorization URL を開くだけです。

## 保存するデータ

一般的な統合では以下の値を保存します。

| 値 | 保存場所 | 重要な理由 |
| --- | --- | --- |
| `projectId` | Backend configuration または database | 1 つの SaaS project を識別します。 |
| `providerConfigId` | Backend configuration または database | project 内の provider config を識別します。runtime calls では優先して使うべきです。 |
| `projectApiKey` | Backend secret manager | Connector runtime calls を認証します。平文の key は 1 回だけ返されます。 |
| `userId` | 製品 database | 製品側のエンドユーザー ID です。Connector は `externalUserId` として保存します。 |
| `connectedAccountId` または `alias` | 製品 database | actions 実行時にエンドユーザーの接続済み account を選択します。 |

ユーザーが複数の Gmail accounts を接続できる場合、各 account の `connectedAccountId` または `alias` を保存し、runtime calls がデフォルトの「最新 account」選択に依存しないようにします。

## ステップ 1: project を作成する

project は SaaS 統合の隔離境界です。provider configs、API keys、connected accounts、execution logs、usage を隔離します。

OOMOL Console で:

![メインパネルに Create project entry がある OOMOL Console Projects page](/img/docs/connector-saas/en/project-list.webp)

1. 左サイドバーから **Projects** を開きます。
2. **Create project** をクリックします。
3. project name を入力します。
4. 作成後、project を開き、project ID を `PROJECT_ID` として保存します。

![Project name field と Create button がある Create project dialog](/img/docs/connector-saas/en/create-project-dialog.webp)

project page には **Provider configs**、**API Keys**、**Connected accounts**、**Execution logs**、**Usage** などの項目があります。残りの setup はこの project 内で行います。

project name は OAuth authorization entry page に表示されます。本番統合では、エンドユーザーが認識できる product name を使い、authorization target を明確にしてください。

## ステップ 2: provider config を作成する

provider config は、この project が 1 つの Connector service に接続する方法を定義します。runtime requests では `providerConfigId` として渡します。Gmail OAuth の場合:

![Create provider config button がある project provider configs page](/img/docs/connector-saas/en/service-configs-page.webp)

1. project sidebar から **Provider configs** を開きます。
2. **Create provider config** をクリックします。
3. 以下の fields を選択または入力します。
4. **Create** をクリックします。

![service、auth type、config identifier、display name、client config source fields がある Create provider config dialog](/img/docs/connector-saas/en/create-service-config-dialog.webp)

| Field | Gmail 例 | Notes |
| --- | --- | --- |
| Service | `Gmail` | 接続する Connector service。 |
| Auth type | `OAuth2` | Gmail は OAuth2 authorization を使用します。 |
| Config slug | `gmail` | backend がこの config に使う読みやすい identifier。同じ project に同一 service の configs が複数ある場合は、`gmail-work` や `gmail-personal` などの名前を使います。 |
| Display name | `Gmail` | authorization entry page でエンドユーザーに表示される名前。 |
| Client config source | `System Client` | OOMOL が提供する OAuth client を使用します。 |

作成後、provider config ID を `PROVIDER_CONFIG_ID` として保存します。backend は authorization links の作成と actions 実行時に明示的に渡すべきです。

各 SaaS project が独自の OAuth client を使う場合、**Client config source** を custom client に変更し、対応する `clientId` と `clientSecret` を提供します。

custom OAuth client では、provider console に Connector callback URL を設定します。OOMOL Console または deployment configuration がその URL を提供します。エンドユーザーはこの URL を必要としません。

API-key service では、対応する API-key auth type を選択します。エンドユーザーが account を接続するとき、backend はユーザーの provider API key を Connector に送信して保存します。

## ステップ 3: project API key を作成する

project API key は backend 専用です。browsers、mobile clients、エンドユーザーの devices には送信しないでください。

project page で:

1. project sidebar から **API Keys** を開きます。
2. **Create API Key** をクリックします。
3. key name を入力します。`production server key` や `staging server key` など、rotation と troubleshooting がしやすい名前を使います。
4. **Create** をクリックします。
5. 1 回だけ表示される dialog から平文 key をコピーし、`PROJECT_API_KEY` として保存します。

![完全な key は二度と表示されないと警告する one-time key dialog](/img/docs/connector-saas/en/api-key-once-dialog.webp)

平文 key は 1 回だけ返されます。以後の一覧には key prefix、creation time、recent usage time などの metadata だけが表示されます。key が漏れた場合は Console で revoke し、新しい key を作成してください。

## ステップ 4: エンドユーザーに account を接続させる

ここからは product runtime flow です。製品に `customer-1` という ID の user がいて、Gmail を接続したいとします。

backend は OAuth authorization link を作成します。

```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"
  }'
```

response には Connector 所有の authorization entry URL である `data.authorizationUrl` が含まれます。エンドユーザーをこの URL にリダイレクトします。

この page は project display title、project icon、provider config display name を短く表示し、その後実際の provider OAuth page にリダイレクトします。ユーザーが認可すると、provider は Connector に callback し、Connector は指定された `returnUri` にリダイレクトします。

成功時、`returnUri` は次のような query parameters を受け取ります。

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

frontend は `connectedAccountId` を backend に送信して保存できます。backend は connection request status を問い合わせることもできます。

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

ユーザーがキャンセルした場合や provider が error を返した場合、`returnUri` は次を受け取ります。

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

`returnUri` は `http` または `https` を使う必要があります。OAuth links はデフォルトで 10 分後に期限切れになります。

## ステップ 5: action を実行する

account が接続された後、backend は保存済み account selector で actions を実行できます。

```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` のどちらか 1 つだけを渡します。本番統合では `providerConfigId` を優先してください。
- `connectedAccountId` または `alias` は多くても 1 つだけ渡します。本番統合ではどちらかを明示的に渡してください。
- account selector がない場合、Connector は同じ `projectId + providerConfigId + userId` 配下の最新 active connected account を選びます。
- action ID の service prefix は provider config service と一致する必要があります。たとえば `gmail.send_email` は Gmail provider config を使う必要があります。

success response には `executionId`、`actionId`、action output が含まれます。support と troubleshooting のために、`executionId` を自社 operation logs に保存してください。

## ステップ 6: user connections を管理する

製品では通常、ユーザーに接続済み accounts を表示する必要があります。推奨される方法は、成功 callback 後に `connectedAccountId`、`alias`、`service`、`providerConfigId`、自社の `userId` を製品 database に保存し、そのデータから account list を表示することです。

Connector 側の状態を確認するには、OOMOL Console の **Connected accounts** で現在の project 配下の connected accounts を確認します。

`available` field は、その account が現在 actions を実行できるかを示します。provider config が active、connected account が active、underlying app が active、credential が存在する場合にのみ `true` になります。

製品でユーザーが accounts の名前を変更できる場合は、まず製品 database の display name を更新します。管理者が Connector 側の状態を確認する必要がある場合は、Console で対応 account を確認します。

ユーザーが account を disconnect する場合、製品 backend で disconnect flow を実行し、製品 database を更新します。管理者は Console で account がまだ available か確認できます。

Disconnect は connected account record を保持しますが、underlying credential を削除します。過去の logs は account を参照できますが、future actions では使用できません。

## ステップ 7: トラブルシューティングと運用

ユーザーの action をトラブルシュートするときは、OOMOL Console の **Execution logs** を開きます。よく使う filters は `providerConfigId`、`userId`、`appId`、`status=success|error`、`action` です。

troubleshooting では、まず service または provider config で表示を絞ります。operation logs に `executionId` を保存している場合、それを使って product-side operation と Connector-side log を結び付けます。

運用では **Usage** を使い、daily usage trends と service ごとの usage を確認します。一般的な windows は 7、30、90 日です。

`days` は `7`、`30`、`90` のみをサポートします。

## runtime で backend が呼び出すもの

このガイドの Gmail OAuth flow では、backend は 3 つの job を処理します。

- authorization link を作成し、ユーザーを Connector authorization entry に送る。
- callback 後に connection request を確認し、`connectedAccountId` を保存する。
- ユーザーが product feature をトリガーしたとき、保存済み account で actions を実行する。

project 作成、provider config 作成、project API key 作成、connected accounts の確認、execution logs の読み取り、usage の確認などの setup と operations には OOMOL Console を優先してください。

## トラブルシューティング

account connection または action execution が失敗した場合は、以下の順序で確認します。

1. backend が現在の project の `PROJECT_API_KEY` を使用しており、その key が browsers や mobile clients に露出していないことを確認します。
2. request が作成した provider config の `providerConfigId` を使用していることを確認します。
3. 同じ user が既存の `alias` を再利用していないことを確認します。
4. Console の **Connected accounts** を開き、account がまだ available か確認します。
5. Console の **Execution logs** を開き、provider config、user ID、または `executionId` で filter します。