網路、介面與外部資料
這一組服務負責「跟 Google 以外的世界打交道」:呼叫外部 API、對外提供網頁或 API、畫出介面、翻譯、地圖、圖表,以及連外部資料庫。總表與星等說明見 內建服務。
UrlFetchApp
常用度:★★★★☆ 常搭配的觸發:時間驅動、選單、自訂函式。簡易觸發不可用
Apps Script 沒有瀏覽器的 fetch,對外 HTTP 請求一律走 UrlFetchApp。GET、POST、帶標頭都可以,回應用 getContentText() 讀出再 JSON.parse。POST 與金鑰放法見 UrlFetchApp 與外部 API。
範例:每天記錄一個 GitHub 專案的星星數
function logStars() {
const res = UrlFetchApp.fetch(
"https://api.github.com/repos/googleworkspace/apps-script-samples",
{ muteHttpExceptions: true }
);
if (res.getResponseCode() !== 200) {
throw new Error("GitHub API " + res.getResponseCode());
}
const data = JSON.parse(res.getContentText());
SpreadsheetApp.getActive()
.getSheetByName("星數")
.appendRow([new Date(), data.stargazers_count]);
}
掛每日時間驅動,一個月後試算表就是一條成長曲線。每天的呼叫次數有上限(一般帳號 20,000 次),迴圈裡連續呼叫時要留意。
HtmlService
常用度:★★★☆☆ 常搭配的觸發:選單(開側欄或對話方塊)、doGet(網頁)
產生 HTML 畫面:可以放在試算表側欄、彈出對話方塊,或當作 Web App 的網頁。前端要呼叫後端函式時,在 HTML 裡用 google.script.run.函式名稱()。
範例:在試算表加一個選單,按下去開啟側欄
function onOpen() {
SpreadsheetApp.getUi()
.createMenu("工具")
.addItem("開啟面板", "showSidebar")
.addToUi();
}
function showSidebar() {
const html = HtmlService.createHtmlOutput("<h3>你好</h3><p>這是側欄。</p>")
.setTitle("小面板");
SpreadsheetApp.getUi().showSidebar(html);
}
畫面複雜時,改在專案裡新增 HTML 檔,用 HtmlService.createHtmlOutputFromFile("檔名") 載入。選單的更多寫法見 自訂選單。
ContentService
常用度:★★★☆☆ 常搭配的觸發:doGet、doPost(Web App)
讓 Web App 回傳純文字、JSON 或 XML,而不是 HTML 網頁。要把 GAS 當成 API 或 Webhook 接收端,回傳值一定是它。
範例:把試算表變成一支唯讀的 JSON API
function doGet() {
const values = SpreadsheetApp.openById("試算表ID")
.getSheetByName("商品")
.getDataRange()
.getValues();
const [header, ...rows] = values;
const items = rows.map((r) => Object.fromEntries(header.map((h, i) => [h, r[i]])));
return ContentService.createTextOutput(JSON.stringify(items))
.setMimeType(ContentService.MimeType.JSON);
}
部署成 Web App 後,別的程式或網頁打這個網址就拿得到商品清單。部署的三個設定見 網頁應用程式;doPost 的實戰見 LINE Bot。
LanguageApp
常用度:★★☆☆☆ 常搭配的觸發:自訂函式、任何觸發。屬於匿名服務,簡易觸發與自訂函式都能用
呼叫 Google 翻譯。每日翻譯次數有上限(一般帳號 5,000 次)。
範例:做一個 =TO_ZHTW(A2) 的自訂函式,把外文翻成繁體中文
/**
* 把文字翻成繁體中文
* @param {string} text 要翻譯的文字
* @return {string} 翻譯結果
* @customfunction
*/
function TO_ZHTW(text) {
return LanguageApp.translate(text, "", "zh-TW"); // 來源語言留空表示自動偵測
}
Maps
常用度:★★☆☆☆ 常搭配的觸發:選單、時間驅動、自訂函式
地址與座標互轉(地理編碼)、路線、距離。每日有各項查詢次數上限(一般帳號地理編碼 1,000 次)。
範例:把「門市」工作表 A 欄的地址,轉成 B、C 欄的緯度與經度
function geocodeAddresses() {
const sheet = SpreadsheetApp.getActive().getSheetByName("門市");
const addresses = sheet.getRange(2, 1, sheet.getLastRow() - 1, 1).getValues();
const out = addresses.map(([addr]) => {
const res = Maps.newGeocoder().setLanguage("zh-TW").geocode(addr);
const loc = res.results.length ? res.results[0].geometry.location : null;
return loc ? [loc.lat, loc.lng] : ["", ""]; // 查不到就留空
});
sheet.getRange(2, 2, out.length, 2).setValues(out);
}
Charts
常用度:★★☆☆☆ 常搭配的觸發:時間驅動搭配寄信、doGet
用程式產生圖表,可以輸出成圖片。注意:想在試算表裡放圖表,是用 SpreadsheetApp 的 sheet.newChart();Charts 服務是用在試算表之外,例如把圖做成附件寄出去。
範例:產生長條圖,當附件寄出
function mailChart() {
const data = Charts.newDataTable()
.addColumn(Charts.ColumnType.STRING, "月份")
.addColumn(Charts.ColumnType.NUMBER, "營收")
.addRow(["1 月", 120])
.addRow(["2 月", 150])
.addRow(["3 月", 180])
.build();
const chart = Charts.newColumnChart().setDataTable(data).setTitle("每月營收").build();
MailApp.sendEmail({
to: Session.getEffectiveUser().getEmail(),
subject: "每月營收圖表",
body: "圖表如附件。",
attachments: [chart.getAs("image/png")],
});
}
JDBC
常用度:★☆☆☆☆ 常搭配的觸發:時間驅動、選單、自訂函式
連接外部關聯式資料庫,如 MySQL、SQL Server、Oracle、Google Cloud SQL。用得上的人不多,因為要先讓資料庫對外開放,且連線次數有每日配額(一般帳號 10,000 次,失敗 100 次)。
範例:從 MySQL 讀出前 10 位客戶
function readCustomers() {
const props = PropertiesService.getScriptProperties();
const conn = Jdbc.getConnection(
"jdbc:mysql://主機:3306/資料庫",
props.getProperty("DB_USER"),
props.getProperty("DB_PASSWORD") // 帳密放屬性,不要寫進程式碼
);
const rs = conn.createStatement().executeQuery("SELECT id, name FROM customers LIMIT 10");
while (rs.next()) {
Logger.log(rs.getString("id") + " " + rs.getString("name"));
}
rs.close();
conn.close();
}
資料庫的防火牆必須允許 Apps Script 的來源 IP,官方文件有列出範圍:JDBC 指南。
下一步:工具服務。