# Google Sheet 串接

本頁在引導使用者如何利用 Google Apps Script，將 MaiAgent 的強大 AI 功能整合到 Google Sheets 中。透過這種方式，您將能夠直接在表格中呼叫您的 MaiAgent Chatbot，並實現對多個輸入的批次處理，大幅提升工作效率。

## 開始設定

### 步驟一：開啟 Google Apps Script 編輯器

1. 打開您想要整合 MaiAgent 的 Google Sheet 試算表，或者建立一個新的試算表。
2. 點擊頂部選單的「擴充功能」 > 「Apps Script」。&#x20;

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2FVpzTpGSgNSpluKWaGTmt%2F%E6%88%AA%E5%9C%96%202025-05-09%20%E4%B8%8B%E5%8D%883.35.40.png?alt=media&#x26;token=63284cb9-ae4e-497d-8e00-2eeee533e147" alt=""><figcaption></figcaption></figure>

### 步驟二：貼上並設定指令碼

1. 在 Apps Script 編輯器中，您會看到一個名為 `Code.gs` 的檔案。將其中預設的內容清空。
2. 將最下方[附件](#fu-jian) MaiAgent 提供的 Apps Script 程式碼完整複製並貼到 `Code.gs` 檔案中。
3. **更換開頭的 API\_KEY 與 CHATBOT\_ID。**
4. 更換後，點擊編輯器上方的儲存圖示 （💾） 來儲存您的指令碼。

## 在 Google Sheet 中使用 MaiAgent 函式

完成上述設定並成功授權後，您就可以在 Google Sheet 中像使用內建函式一樣使用 `maiagent` 函式了。

#### 1. 單一呼叫 Agent

在任何儲存格中，輸入以下格式的公式：

`=maiagent("您想要傳送給 Agent 的訊息內容")`

例如：

* `=maiagent("你好，請介紹一下你自己")`
* `=maiagent("今天天氣真好")`

按下 Enter 後，指令碼會將您的訊息傳送給指定的 MaiAgent AI 助理，並將 AI 助理的回應內容顯示在該儲存格中。

#### 2. 從其他儲存格讀取訊息內容

您可以讓 `maiagent` 函式讀取其他儲存格的內容作為輸入訊息。

假設儲存格 `A1` 包含您想要傳送的訊息，您可以在另一個儲存格（例如 `B1`）中輸入：

`=maiagent(A1)`

這樣，`B1` 儲存格就會顯示 MaiAgent 對 `A1` 內容的回應。

## 串接成果影片

{% embed url="https://drive.google.com/file/d/1NsRpwWGxWpakkRNyXh2WJeBN3Kzw6yDY/view?usp=sharing" %}

## 結論

透過 Google Apps Script 將 MaiAgent 整合至 Google Sheets，為自動化和提升生產力開闢了新的可能性。技術人員可以利用此方法，根據具體需求客製化試算表，使其成為強大的 AI 互動工具，無論是內容生成、資料分析還是自動化應答，都能更加得心應手。

## **附件**

{% code title="Apps Script 程式碼" %}
```javascript
// --- 在這裡定義您的 API 金鑰和 Chatbot ID ---
const API_KEY = '<請替換成您實際的 API 金鑰>';
const CHATBOT_ID = '<請替換成您實際的 Chatbot ID>';
// --- --- --- --- --- --- --- --- --- --- --- ---

/**
 * 向 MaiAgent API 發送訊息並直接返回回應內容。
 * API 金鑰和 Chatbot ID 使用腳本開頭定義的常數。
 * is_streaming 固定為 false，不傳送 conversation 和 attachments。
 *
 * @param {string} messageContent 要發送的訊息內容。
 * @return {string} API 回應中的 "content" 欄位內容，或錯誤訊息。
 */
function maiagent(messageContent) {
  // 檢查 API_KEY 和 CHATBOT_ID 是否已設定
  if (API_KEY === 'YOUR_API_KEY' || CHATBOT_ID === 'YOUR_CHATBOT_ID') {
    const warningMessage = '警告：API 金鑰或 Chatbot ID 尚未在腳本中設定。請編輯腳本並替換 YOUR_API_KEY 和 YOUR_CHATBOT_ID。';
    Logger.log(warningMessage);
    // 可以選擇在這裡拋出錯誤或返回警告，以防止無效的 API 呼叫
    // throw new Error(warningMessage);
    return warningMessage;
  }

  const url = `https://api.maiagent.ai/api/v1/chatbots/${CHATBOT_ID}/completions/`;

  const payload = {
    message: {
      content: messageContent
    },
    is_streaming: false
  };

  const options = {
    method: 'post',
    contentType: 'application/json',
    headers: {
      'Authorization': `Api-Key ${API_KEY}`
    },
    payload: JSON.stringify(payload),
    muteHttpExceptions: true // 設定為 true 以便處理 API 可能回傳的錯誤訊息
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    const responseCode = response.getResponseCode();
    const responseBody = response.getContentText();

    if (responseCode === 200) {
      Logger.log('API 呼叫成功:');
      Logger.log(responseBody); // 仍然記錄完整的原始回應，方便偵錯
      try {
        const jsonResponse = JSON.parse(responseBody);
        if (jsonResponse && typeof jsonResponse.content !== 'undefined') {
          return jsonResponse.content; // 直接返回 content 欄位的值
        } else {
          Logger.log('API 回應成功，但缺少 "content" 欄位或格式不符。');
          Logger.log(responseBody);
          return '錯誤: API 回應成功，但缺少 "content" 欄位。';
        }
      } catch (parseError) {
        Logger.log(`解析 API 回應 JSON 時發生錯誤: ${parseError.toString()}`);
        Logger.log(`原始回應內容: ${responseBody}`);
        return `錯誤: 解析 API 回應失敗 - ${parseError.toString()}`;
      }
    } else {
      Logger.log(`API 呼叫失敗，回應代碼: ${responseCode}`);
      Logger.log(`錯誤回應內容: ${responseBody}`);
      return `錯誤: ${responseCode} - ${responseBody}`;
    }
  } catch (e) {
    Logger.log(`API 呼叫時發生異常: ${e.toString()}`);
    Logger.log(e.stack); // 記錄堆疊追蹤，方便更詳細的偵錯
    return `異常: ${e.toString()}`;
  }
}
```
{% endcode %}
