GAS UrlFetch 串接外部 API

UrlFetchApp 是 GAS 與外接世界溝通的橋樑。它能發送 HTTP 請求（GET, POST, PUT, DELETE 等），讓你與 Slack, Line, Notion 或公司的私有 API 進行串接。

基礎 GET 請求

最簡單的呼叫，用來取得 JSON 格式的外部資料。

/**
 * 取得外部天氣 API 資料
 */
function fetchWeather() {
  const url = "https://api.example.com/weather?city=Taipei";
  const response = UrlFetchApp.fetch(url);
  
  const json = JSON.parse(response.getContentText());
  console.log(`目前溫度：${json.temp} 度`);
}

進階 POST 請求與 Headers

當你需要傳送資料給外部伺服器或傳遞 API Key 時。

/**
 * 發送資料給第三方 API
 */
function postDataToAPI() {
  const url = "https://api.example.com/v1/orders";
  const payload = {
    orderId: "12345",
    amount: 500
  };
  
  const options = {
    method: 'post',
    contentType: 'application/json',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'X-Custom-Header': 'GAS-App'
    },
    payload: JSON.stringify(payload),
    muteHttpExceptions: true // 發生錯誤時不中斷腳本
  };
  
  const response = UrlFetchApp.fetch(url, options);
  const code = response.getResponseCode();
  
  if (code === 200 || code === 201) {
    console.log('成功送出！');
  } else {
    console.warn(`錯誤代碼：${code}, 內容：${response.getContentText()}`);
  }
}

核心 UrlFetch 函數語法說明

UrlFetchApp.fetch(url, params)

• url：要請求的網址。
• params (選填物件)：
  • method：'get', 'post', 'put', 'delete' 等。
  • contentType：常見為 'application/json' 或 'application/x-www-form-urlencoded'。
  • headers：自定義的標頭。
  • payload：要傳出的資料內容（物件或 JSON 字串）。
  • muteHttpExceptions：若設為 true，遇到 404 或 500 錯誤時會繼續執行，並讓你判斷 Response Code。

HTTPResponse 物件方法

• getContentText()：取得內容文字（通常是 JSON 字串）。
• getResponseCode()：取得 HTTP 狀態碼 (如 200, 404)。
• getHeaders()：取得伺服器回傳的標頭訊息。

處理 API 錯誤技巧

與外部 API 溝通時，網路不穩或 API 掛掉是常態。建議務必使用 try...catch 配合 muteHttpExceptions。

try {
  const response = UrlFetchApp.fetch(url, options);
  // 處理正常邏輯
} catch (e) {
  // 處理超時或 DNS 錯誤等極端情況
  MailApp.sendEmail("admin@example.com", "API 警報", e.toString());
}

執行配額限制

• 單次請求時間：上限約為 60 秒。
• 每日請求次數：普通帳戶約 20,000 次，Workspace 約 100,000 次。
• 單次資料大小：通常限制在 10MB ~ 50MB 之間。