> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 工具串接教學：商品庫存查詢

> 用 2 分 35 秒影片，學會讓 AI 助理透過商品 API 查詢價格與庫存，從共用連線、參數到回傳欄位與測試。

客戶打來問：「一號商品，還有貨嗎？」接上商品 API 後，AI 助理就能帶入商品編號，查到庫存，再依結果回答。

<video controls playsInline preload="metadata" poster="/images/tutorials/product-api-cover.png" src="https://mintcdn.com/brightalk/w2jEeyGa90l6GD4n/videos/product-api-tutorial.mp4?fit=max&auto=format&n=w2jEeyGa90l6GD4n&q=85&s=2b1ef0ce5ece5f6a71698ee6a6c3ac45" alt="API 工具串接教學：商品庫存查詢，含中文旁白與繁體字幕" aria-label="API 工具串接教學：商品庫存查詢，2 分 35 秒">
  你的瀏覽器無法播放這支影片，請參考下方完整操作步驟。
</video>

影片長 **2 分 35 秒**，含中文旁白與繁體字幕。下方設定可直接照做。

## 這次要完成的流程

1. 客戶提供商品編號，例如 `1`。
2. `lookup_product` 工具向商品系統送出 `GET /products/1`。
3. AI 取得商品名稱、價格與庫存，回答客戶的問題。

本例使用 [DummyJSON 商品範例](https://dummyjson.com/docs/products)。範例資料與真實商店的庫存分開；換成自己的 API 後，才會查到自己的商品。

開始前，準備一位要使用工具的 AI 助理，並確認帳號有整合管理權限。到「設定 → 整合 → [API 工具與資料](https://www.brightalk.ai/settings/integrations/api-tools)」開始設定。

## 1. 建立共用連線

在「共用連線」點「新增連線」，填入以下內容並儲存。

| 欄位 | 本例設定 |
| - | - |
| 名稱 | 商品 API |
| API 基底網址 | `https://dummyjson.com` |
| 認證方式 | 不需要認證 |

連線負責 API 網址與認證。自己的系統若需要金鑰，依對方文件選擇「Bearer token」或「自訂認證 Header」，再填入憑證。

## 2. 定義查詢工具

點「新增查詢工具」，在「基本設定」完成以下設定。

* **工具名稱**：`lookup_product`
* **使用連線**：剛建立的「商品 API」
* **使用範圍**：選擇要處理商品問題的助理
* **啟用工具**：開啟

「何時使用這個工具」可以填入：

```text theme={null}
客戶詢問商品價格或庫存時使用。先確認商品編號，再查詢該商品的名稱、價格與庫存。沒有商品編號時，先詢問客戶。
```

## 3. 把商品編號帶入查詢

切到「查詢參數」，將「查詢路徑」設為 `/products/{product_id}`，再新增一個參數。

| 欄位 | 設定 |
| - | - |
| 參數名稱 | `product_id` |
| 資料類型 | `number`（數字） |
| 參數來源 | 由對話取得 |
| 放置位置 | URL 路徑 |
| 必填 | 開啟 |

大括號內的名稱必須和參數名稱一致。客戶提供編號 `1` 時，查詢路徑就會變成 `/products/1`。

## 4. 選擇交給 AI 的欄位

在「回傳資料」新增以下三個欄位，並將三者設為必填。

| API 回傳欄位路徑 | 交給 AI 的變數名稱 | 用途 |
| - | - | - |
| `title` | `product_name` | 商品名稱 |
| `price` | `unit_price` | 價格 |
| `stock` | `stock_qty` | 庫存數量 |

左欄要和 API 實際回傳的 JSON 結構一致；右欄是回答規則中可引用的名稱。例如自己的 API 將名稱放在 `data.title`，左欄就填 `data.title`。

## 5. 設定回答方式

在「AI 如何使用查詢結果」填入服務規則，再按「儲存設定」。

```text theme={null}
先以 product_name 確認品項，再依 stock_qty 回覆目前庫存；庫存為 0 時說明目前缺貨。
unit_price 依 API 原始數值呈現；缺少幣別時先確認，不自行換算。
資料不足時先詢問，不承諾已保留商品或已下單。
```

## 6. 執行一筆測試

切到「測試與預覽」，在「測試輸入（JSON）」填入：

```json theme={null}
{"product_id": 1}
```

按「執行查詢」，比較「欄位映射前的資料」與「實際交給 AI 的資料」。影片錄製時，映射後的商品欄位如下；測試時請以 API 當次回傳為準。

```json theme={null}
{
  "product_name": "Essence Mascara Lash Princess",
  "unit_price": 9.99,
  "stock_qty": 99
}
```

三個欄位都正確後，這筆查詢的連線、參數與映射就已接通。範例中的庫存是 `99`，助理可回答「這項商品目前還有 99 件」。接著在助理的對話測試中確認：缺少編號時會先詢問，取得編號後會呼叫工具並依查詢結果回答。

## 換成自己的商品系統

向 API 串接人員取得基底網址、認證方式、查詢路徑與回傳 JSON 範例。通用查詢工具目前使用 **HTTPS GET**；將上述連線、參數與欄位替換後，重新測試一筆商品即可。

| 測試時遇到的問題 | 先檢查 |
| - | - |
| 連線或認證失敗 | 基底網址、認證方式與金鑰是否正確或已到期 |
| 參數錯誤或找不到商品 | `product_id` 的名稱、數字類型、URL 路徑位置與商品編號 |
| 缺少必填回傳欄位 | API 的 JSON 結構是否與 `title`、`price`、`stock` 路徑一致 |
| 測試成功，對話中沒有呼叫工具 | 工具是否啟用、使用範圍是否包含該助理，以及使用時機的描述 |

第一次設定助理，可先看[建立外撥 AI 代理教學](https://docs.brightalk.ai/zh-Hant/guides/create-outbound-agent.md)；線路與可用性條件請參考 [AI 語音代理](https://docs.brightalk.ai/zh-Hant/concepts/agents.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.