> For the complete documentation index, see [llms.txt](https://docs.coreway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coreway.com/yoov-plus/worksheet/worksheet-design/field-type/call-api-field.md).

# 調用 API 欄位

## 一、功能簡介 <a href="#id-1-feature-introduction" id="id-1-feature-introduction"></a>

**調用 API** 欄位允許您在表單中添加一個自訂按鈕，使用者點擊該按鈕後，系統會將表單中指定欄位的資料作為參數，發送給外部的 API（例如 YOOV AI Chain 中的 AI 應用）進行處理，並將返回的結果自動填入到表單的對應欄位中。

此功能極大地擴展了表單的處理能力，例如：

* 根據填寫的出發地、目的地和日期，點擊按鈕自動生成並回填「行程安排」。
* 將大段文字發送至翻譯 API，自動將翻譯結果回填至指定欄位。
* 根據輸入的產品描述，調用外部 AI 應用自動生成營銷文案。

## 二、前置準備：配置 API 授權 <a href="#id-2-preparation-configure-api-authorization" id="id-2-preparation-configure-api-authorization"></a>

在表單中使用調用 API 欄位前，管理員需要先在系統中配置 API 的授權令牌（Token）。目前系統支援接入 YOOV 旗下的 YOOV AI Chain 產品。

### 1. 獲取訪問令牌 <a href="#id-2-1-get-access-token" id="id-2-1-get-access-token"></a>

在 [YOOV AI Chain](https://www.yoov.ai/zh-hk) 平台中，生成並複製您的 API 訪問令牌（API Key）。

<figure><img src="/files/LAtoctchZMsk36OuXPSM" alt=""><figcaption></figcaption></figure>

### 2. 在系統中配置授權 <a href="#id-2-2-configure-authorization-in-system" id="id-2-2-configure-authorization-in-system"></a>

{% stepper %}
{% step %}

#### 進入「授權管理」頁面

進入系統的 **團隊管理** > **授權管理** 頁面。
{% endstep %}

{% step %}

#### 新建調用 API 令牌

<figure><img src="/files/W31E5xBdv3rCrkejSRnS" alt=""><figcaption></figcaption></figure>

點擊右上角的 **新建** 按鈕，選擇 **調用 API**。
{% endstep %}

{% step %}

#### 填寫令牌資訊

<figure><img src="/files/grS1SRTeB0YqbJP9uwVC" alt=""><figcaption></figcaption></figure>

在彈出的「新建令牌」視窗中，填寫 **令牌名稱**，並將剛剛獲取的 **令牌（API Key）** 貼上至對應輸入框，點擊確認。
{% endstep %}

{% step %}

#### 授權應用範圍

<figure><img src="/files/YNr6RKaSfujJPSCXb7RO" alt=""><figcaption></figcaption></figure>

建立完成後，在授權列表中找到該令牌，點擊右側的 **操作** > **授權應用**，選擇允許使用此 API 的應用範圍。
{% endstep %}
{% endstepper %}

完成上述配置後，您就可以在表單設計中選擇並使用這個 API 連接了。

## 三、操作流程 <a href="#id-3-operation-process" id="id-3-operation-process"></a>

### 進入欄位配置介面 <a href="#id-3-1-enter-field-configuration-interface" id="id-3-1-enter-field-configuration-interface"></a>

1. 進入目標應用的表單設計介面。
2. 點擊左側導航欄中的 **AI 場景**頁籤。
3. 將 **調用 API** 欄位拖曳至表單設計區域中，右側即會彈出欄位屬性面板。

<figure><img src="/files/2BV5jvz0PtBOxK7BuGNs" alt=""><figcaption></figcaption></figure>

### 配置調用 API 欄位 <a href="#id-3-2-configure-call-api-field" id="id-3-2-configure-call-api-field"></a>

在屬性面板中，您需要完成以下配置：

{% stepper %}
{% step %}

#### 基本屬性設置

* **欄位名稱**：在表單設計器中顯示的控制項名稱（例如：調用API）。
* **按鈕名稱**：實際展示給使用者點擊的按鈕文字（例如：生成行程、開始翻譯）。
  {% endstep %}

{% step %}

#### 選擇 API 連接與介面

* **選擇 API 連接**：在下拉選單中選擇您在「授權管理」中配置好的令牌（例如：行程規劃）。
* **選擇 API**：選擇該連接下具體要調用的 API 介面（例如：行程規劃）。
  {% endstep %}

{% step %}

#### 配置輸入參數

系統會自動讀取所選 API 需要的輸入參數列表。您需要將表單中的欄位與這些參數進行綁定。

<figure><img src="/files/i1xaZ2dGK9fM3jbJswfR" alt=""><figcaption></figcaption></figure>

例如，API 需要「出發日期」、「返回日期」、「目的地」等參數，您可以點擊輸入框右側的圖示，選擇表單中對應的欄位作為變數傳入。
{% endstep %}

{% step %}

#### 配置返回參數（映射關係）

點擊 **返回參數設置** 按鈕，在彈出的「映射關係設置」視窗中，設定 API 返回的結果要填入表單的哪個欄位。

<figure><img src="/files/bOIZjxNXzeOUdCzBWiw7" alt=""><figcaption></figcaption></figure>

* **識別欄位**：API 返回資料中的欄位名稱（例如：`output`）。
* **工作表欄位**：選擇接收該資料的表單欄位（例如：「行程安排」富文本欄位）。
  {% endstep %}
  {% endstepper %}

**其他配置項**：

* **欄位權限**：可見、新建記錄時隱藏。
* **欄位寬度**：可定義控制項在表單頁面的寬度（1/4、1/3、1/2、2/3、3/4、1）。
* **描述信息**：為該按鈕添加補充說明文字。

### 實際運行效果 <a href="#id-3-3-actual-running-effect" id="id-3-3-actual-running-effect"></a>

配置完成後，在表單記錄的填寫或編輯頁面中，會顯示您設定的按鈕。

**點擊前：**

<figure><img src="/files/wNW53sfyUYcV6lxMQlRN" alt=""><figcaption></figcaption></figure>

使用者先在表單中填寫所需的基礎資訊（如出發日期：2026-03-01，目的地：廣東省/廣州市，出行方式：飛機等）。此時「行程安排」欄位為空。

**點擊後：**

<figure><img src="/files/d03GkyYQQKKQghGfur4Q" alt=""><figcaption></figcaption></figure>

使用者點擊 **調用 API** 按鈕。系統會讀取表單中的資訊發送給 AI，處理完成後，生成的「廣州六日五夜深度文化美食之旅」詳細行程規劃會自動填入並顯示在「行程安排」欄位中。

## 四、注意事項 <a href="#id-4-notes" id="id-4-notes"></a>

* **參數完整性**：在點擊調用按鈕前，請確保作為「輸入參數」的表單欄位均已填寫完整，否則可能導致 API 調用失敗或返回結果不準確。
* **等待時間**：點擊按鈕後，根據 API 處理的複雜度，可能需要短暫的等待時間。處理期間請勿關閉頁面。
* **覆蓋規則**：如果「工作表欄位」（接收結果的欄位）中原本已有內容，API 返回的新結果將會 **覆蓋** 原有內容，請謹慎操作。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coreway.com/yoov-plus/worksheet/worksheet-design/field-type/call-api-field.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.