---
title: 使用 SDK 呼叫已連接的 Apps
description: 透過託管 Connector client，讓可信的 TypeScript 後端呼叫你在 OOMOL 帳號中連接的 Apps。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/connector-client/
markdown_url: https://oomol.com/zh-tw/docs/connector-client.md
---

# 使用 SDK 呼叫已連接的 Apps

當後端程式碼需要呼叫你在 OOMOL 帳號中連接的 Apps 時，使用 `Connector`。這條路徑會呼叫 OOMOL 託管的 Connector 閘道，並使用形如 `api_…` 的個人 API key。

## 安裝 SDK

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

SDK 需要 Node 18 或更高版本。其他提供標準 `fetch` 與 `AbortController` API 的環境也可以使用，但個人 API key 必須留在可信的後端環境中。

## 建立個人 API key

在 [OOMOL Console](https://console.oomol.com/api-key) 建立 key，然後儲存為後端密鑰：

```sh
export OOMOL_API_KEY=api_...
```

不要把這個 key 放進瀏覽器 bundle、行動用戶端、公開程式碼倉庫、提示詞或用戶端日誌。

## 執行第一個 action

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

const oomol = new Connector({ apiKey: process.env.OOMOL_API_KEY! });

const result = await oomol.execute("gmail.search_threads", {
  query: "is:unread",
});
```

Namespace 寫法會執行同一個 action：

```ts
const result = await oomol.gmail.search_threads({ query: "is:unread" });
```

需要在日誌或支援工單中保存 `executionId`、`actionId` 和回應訊息時，使用 `executeRaw`。

## 選擇已連接帳號

同一個 provider 有多個 connection 時，透過 `connectionName` 選擇帳號：

```ts
await oomol.execute(
  "gmail.search_threads",
  { query: "from:ceo" },
  { connectionName: "work" },
);
```

使用 `oomol.apps.list()` 查看目前 OOMOL 帳號可用的 connections。Connection 的建立與移除仍在 OOMOL Console 中完成。

## 尋找 actions

透過 catalog 查看 providers、actions 與執行時 schemas：

```ts
const providers = await oomol.catalog.providers({ q: "mail" });
const actions = await oomol.catalog.actions("gmail");
const action = await oomol.catalog.action("gmail.search_threads");
```

上游 endpoint 還沒有對應 action 時，可以使用 `proxy` 透過所選 connection 呼叫。

## 繼續查閱參考

[TypeScript SDK 參考](/zh-tw/docs/connector-sdk/)包含精確的 action 類型、設定優先順序、重試、逾時、取消、proxy 行為、錯誤處理和完整的 `Connector` API。

如果產品裡的每個使用者都要連接獨立帳號，請改用 [ProjectConnector](/zh-tw/docs/project-connector/)。