# Google Sheet 串接

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

## 開始設定

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

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

<figure><img src="/files/ZaYHpRYAmVPpDDJIK1X6" 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 %}


---

# Agent Instructions: 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:

```
GET https://docs.maiagent.ai/tech/others/google-sheet-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.