---
title: "外部服務與 ERP 系統串接"
category: "api-and-integration"
canonical: "https://www.ai-go.app/zh-TW/docs/guide/external-connectors"
locale: "zh-TW"
last_updated: "2026-08-10"
source: "AI GO 開發者文件（https://www.ai-go.app）"
---

# 外部服務與 ERP 系統串接

前一章講的是**別人怎麼呼叫 AI GO**。這一章講反方向——**AI GO 怎麼呼叫別人**。

平台有兩套機制，用途不同：

| 機制 | 用途 | 設定位置 |
|---|---|---|
| **外部服務（Egress）** | Custom App 呼叫任意外部 API | Builder 的「外部服務」分頁 |
| **外部數據串接（Connectors）** | 與既有 ERP／資料庫做欄位級同步 | 主控台「資料中心 › 外部數據」 |

---

## 1. 外部服務：應用程式的對外出口

Custom App 不能隨意連上網際網路。所有對外呼叫都必須經過**授權過的外部服務**，這是刻意的設計——避免應用程式把企業資料送到未經核可的地方。

### 設定入口

**Builder 的「外部服務」分頁是唯一入口。** 這裡設定的是「這個應用程式可以呼叫哪些外部服務」。

### 網域白名單

授權以**網域**為單位：您授權 `api.logistics.example.com`，該應用就只能呼叫這個網域底下的路徑。未授權的網域一律呼叫不到，不論程式碼怎麼寫。

### 認證方式：金鑰歸應用程式自管

閘道**只做網域驗證**——不代管金鑰、不注入也不剝除 `Authorization` header。
對外 API 的憑證存放在應用程式的 **App Secrets**（`ctx.secrets`），由 Server Action
在呼叫時自行組出認證 header：

```python
def execute(ctx):
    resp = ctx.http.call('logistics', '/track',
                         method='POST',
                         headers={'Authorization': f"Bearer {ctx.secrets.get('LOGISTICS_KEY')}"},
                         body={'no': ctx.params['tracking_no']})
```

若外部 API 回 401，代表**應用程式自帶的憑證有問題**（header 沒組對、金鑰過期）——
檢查 App Secrets 與程式碼，不需要動外部服務設定。

### 在程式碼中使用

```python
def execute(ctx):
    resp = ctx.http.call('logistics', '/track',
                         method='POST',
                         body={'no': ctx.params['tracking_no']})

    if resp['status'] != 200:
        # data 帶 error_type / error / fix
        return ctx.response.json({'error': resp['data'].get('fix')})

    ctx.response.json(resp['data'])
```

第一個參數是**服務代號**（不是完整網址），路徑會接在該服務的基底網址後面。

### 可行動的錯誤訊息

外部呼叫失敗時，回應的 `data` 會帶三個欄位：

| 欄位 | 內容 |
|---|---|
| `error_type` | 錯誤分類（未授權、逾時、憑證錯誤、網域未白名單⋯） |
| `error` | 技術訊息 |
| `fix` | **一句可直接轉述給使用者的修復指引** |

`fix` 是刻意設計的——它讓應用程式可以把「怎麼修」直接顯示給操作者，而不是丟一個技術堆疊。Builder 介面與 AI 開發助手也會讀取這個欄位來協助排錯。

### 授權缺漏的症狀

程式碼呼叫了沒有建立同名外部服務、或未授權給本應用的服務時，執行期會被閘道擋下，
回應的 `fix` 欄位會指出缺什麼。平台**不驗證也不保管金鑰**——金鑰缺漏要到實際呼叫
外部 API 收到 401 才會浮現，屬應用程式側要處理的錯誤。

### 抓取任意網址

除了具名服務，`ctx.http.fetch` 可以抓取任意公開網址（例如讀取公開的匯率或公告頁面）。安全限制仍然完整保留——不能藉此存取內部網路位址。

---

## 2. 外部數據串接：與既有系統同步

**入口**：主控台「資料中心 › 外部數據」，需要 `system.admin` 權限。

與「外部服務」不同，這套機制處理的是**結構化的資料同步**——把既有 ERP 或資料庫的資料與 AI GO 的資料模型對應起來，定期雙向同步。

### 支援的來源

- 通用 RESTful API
- 通用外部資料庫（PostgreSQL、MySQL 等）
- 主流 ERP 系統的預設連線設定

建立資料來源後可以「測試連線」，即時檢測連通性與健康狀態。

### 欄位映射

連上來源後，需要把外部的欄位與 AI GO 的資料模型對應起來。

**映射模板**：常見的 ERP 系統提供預設映射模板（客戶主檔、產品主檔等），可用精靈快速套用。

**AI 映射建議**：對接自訂表或非標準系統時，可使用 AI 自動建議——系統會分析外部欄位名稱、資料型態與 AI GO 欄位的語意相似度，提出最佳對應。這大幅降低了逐欄設定的負擔。

### 同步方向與日誌

| 方向 | 說明 |
|---|---|
| 外部 → AI GO | 唯讀拉取 |
| AI GO → 外部 | 寫回外部系統 |
| 雙向 | 兩邊互相同步 |

同步日誌記錄每次執行的時間、異動筆數、成功狀態與錯誤訊息，供追蹤資料一致性與排查問題。

---

## 3. 該用哪一個

| 情境 | 用哪個 |
|---|---|
| 應用程式要呼叫簡訊 API 發驗證碼 | 外部服務 |
| 應用程式要查物流狀態 | 外部服務 |
| 應用程式要呼叫自己的模型 API | 外部服務 ＋ App Secrets |
| 把既有 ERP 的客戶主檔同步進來 | 外部數據串接 |
| 讓兩套系統的訂單資料保持一致 | 外部數據串接 |
| 一次性把舊系統資料搬進來 | **資料匯入**（第 6 章） |

判準：**單次呼叫用外部服務，持續同步用串接，一次性搬遷用匯入。**

---

## 4. 反方向：讓外部系統推送給您

若外部系統支援事件推送，不需要輪詢——用 Webhook 讓它主動打進來。

在 Custom App 的 Action 上開啟 Webhook 即可取得對外端點：

```
POST https://{app 子網域}/webhook/{action_name}
```

**請務必在 Action 內驗證來源**（例如以 `ctx.crypto.hmac_sign` 比對簽章）。詳見第 9 章。

---

## 5. 安全邊界摘要

- 應用程式**只能**呼叫被明確授權的網域
- 對外憑證存放在 App Secrets，不落在應用程式的原始碼裡
- 內部網路位址受保護，不能透過抓取任意網址繞過
- 呼叫外部服務需要 `http` scope，屬於高風險等級——授權時需要擁有者密碼再驗證
- 每一次對外呼叫都留下稽核紀錄