資料來源
Data Source（資料來源）是儲存在文件中的命名查詢，其結果始終是一張表格：來自 Web API、SQLite 資料庫檔案或任何通過 ODBC 存取的資料庫的行。你在一個邊輸入邊顯示錶格的編輯器中構建它，文件會在任何可以放置表格的位置顯示它：溢位到活頁簿的儲存格中，或作為 Impulse 文件中或 Expo 投影片上的智慧表格。重新整理它，表格就會隨資料來源更新，同時保留你為每一列設定的格式。
Data Source 是資料，而不是程式碼：它不需要等待 Enable，但在你允許它存取之前，它無法存取任何內容（參見信任）。
建立 Data Source
| 應用程式 | 建立 | 編輯 |
|---|---|---|
| Formula | Data ▸ New Data Source… | 選中其表格中的某個儲存格後使用 Data ▸ Edit Data Source…；Properties 面板中的 Edit Data Source… 會在 Data Sources 索引標籤中開啟它 |
| Impulse | Insert ▸ Data Source… 把它作為智慧表格放在插入點處 | References ▸ Edit Data Source…，或表格的右鍵選單 |
| Expo | Insert ▸ Data Source… 把它作為智慧表格放在投影片上 | 表格的右鍵選單 |
在 Formula 中，Data Source 是一個公式 =DATASOURCE("Sales")，它會像任何動態陣列一樣，從儲存格溢位其表格。
編輯器
- Name：文件對它的稱呼，例如
=DATASOURCE("Sales")中的名稱。 - Reads from：Web API、SQLite file 或 ODBC。
- Web API：一個返回 JSON 的 URL，其查詢參數每行一個（
region = {param.Region}），其請求頭每行一個（Authorization: Bearer {credential.secret}），以及 Rows，即指向行陣列的 JSON 路徑，例如$.data.items（留空時為整個響應）。只發出 GET 請求。 - SQLite file：資料庫檔案，可以是文件旁邊的路徑（
Sales.db），也可以是完整路徑；它以只讀方式開啟。 - ODBC：一個連線字串，例如
DSN=Sales。
- Web API：一個返回 JSON 的 URL，其查詢參數每行一個（
- Query（用於資料庫）：一條
SELECT（或WITH … SELECT）語句；不接受任何寫入操作。SQL 中的param.Region讀取文件的 Region 參數，並作為值傳送，絕不會被拼接進語句中，因此參數無法改變查詢的行為。 - Credential：儲存在你電腦上（絕不儲存在文件中）的使用者名稱和金鑰，連線字串、URL 或請求頭以
{credential.user}和{credential.secret}讀取它們。旁邊的鎖形按鈕會把新認證儲存到 Windows 認證管理器中，名稱為MethodoxOffice:<name>。文件只儲存認證的名稱，因此每個開啟它的人都使用自己的認證。 - Refresh：Manually、When the document opens 或 Every few minutes（除非你更改，否則每 15 分鐘一次）。當資料來源讀取的參數發生變化時，它總會重新整理。
右側的表格是資料來源的結果，每次更改後片刻就會重新讀取，因此你看到的就是你正在構建的表格；當資料來源需要文件尚未獲得的存取權限時，旁邊會出現一個 Allow 按鈕。一旦讀取得到結果，其下方就會出現 Columns，列出資料來源返回的內容（在此之前沒有可列出的內容，因此不會顯示）：取消勾選某列可將其排除，在 Shown as 下重新命名，設定其初始的數字格式和寬度，以及上移或下移。OK 會將 Data Source 作為一次可復原的更改儲存在文件中。一個 Data Source 最多返回 100,000 行。
Data Sources 索引標籤
Formula 中的 Data ▸ Data Sources，或 Impulse 和 Expo 中的 Tools ▸ Data Sources，會在底部托盤中開啟一個索引標籤，在一處列出文件的所有 Data Source：其名稱、Kind（Web API、SQLite 或 ODBC）、Reads（讀取的內容）、Shown In（表格顯示的位置）、上次重新整理時間、Status 和上一個錯誤、Rows，以及是否擁有所需的 Access。資料來源右鍵選單中的 Show in Data Sources 項，以及它在 Smart Objects 索引標籤中的行，都會在該資料來源處開啟此索引標籤。
- New Data Source… 和 Edit Data Source… 會開啟編輯器。
- Refresh 重新整理所選的資料來源，Refresh All 重新整理所有資料來源。
- Rename… 重新命名資料來源，並在同一個復原步驟中改寫所有呼叫它的
=DATASOURCE("…")公式，同時保留其上次的結果，因此任何顯示它的地方都不會變成錯誤。 - Duplicate 建立一個副本以供修改；Delete 在詢問後刪除資料來源，並說明它仍在何處顯示。
- Go To（或按兩下該行）會轉到它所填充的表格；Insert at Selection 會把它放在儲存格或插入點處：在 Formula 中作為溢位的
=DATASOURCE()，在 Impulse 和 Expo 中作為智慧表格。 - Allow 授予資料來源所需的權限，與文件上方的欄作用相同。
重新整理
- Formula： Data ▸ Refresh Data（
Ctrl+Shift+F5）重新整理活頁簿中的所有 Data Source 和資料來源 Function。 - Impulse 和 Expo： Data Source 是一個智慧物件，通過 Refresh All（
Ctrl+Shift+F9）與其他智慧物件一起重新整理，或從其右鍵選單重新整理。 - 自動重新整理：按照每個資料來源的 Refresh 設定進行，以及在其讀取的參數發生變化時進行。
在兩次重新整理之間，以及在離線開啟的文件中，表格顯示上次重新整理取得的內容，這些內容隨文件一起儲存。Data Sources 索引標籤列出所有 Data Source 及其上次重新整理時間和結果；上次重新整理的時間隨文件一起儲存。Smart Objects 索引標籤也在 Data sources 下列出了它們。
信任與存取
讀取 Data Source 會存取文件之外的內容，因此必須允許文件這樣做：
- Web API 需要對其網站的 GET 權限，例如 Needs GET api.open-meteo.com；
- 資料庫需要對其檔案或連線的 Connect 權限，例如 Needs Connect Sales.db。
文件上方的欄或編輯器的預覽會通過 Allow 按鈕發出請求。每項授權都會針對該文件記錄在你的信任儲存中，並與決定資料來源連線到何處以及查詢什麼的內容相關聯；因此在其他地方編輯資料來源的連線或查詢會再次詢問，而你在編輯器中所做的編輯會保留文件的授權。資料來源表格的外觀不計入其中。
按列名設定表格格式
Data Source 或任何智慧表格在每次重新整理時都會被重寫，其列可能以另一種順序返回，或者多一列、少一列。因此你可以像對待任何表格一樣為它設定格式，而格式屬於列的名稱，而非其位置：每次重新整理後，每一列都會按其標題恢復外觀、寬度和數字格式。
- Formula： 溢位的表格會保留每一列的儲存格格式、寬度以及其中的條件格式。
- Impulse： 智慧表格會保留每一列的儲存格格式、文字格式及其寬度。表格右鍵選單中的 Column Number Format… 用於設定某列數字的寫法。
- Expo： 列的外觀由其標題儲存格和第一個正文儲存格決定，並應用到每一行。選中表格或其中某個儲存格，用文字格式欄設定格式；Column Number Format… 位於右鍵選單中。
Data Source，或在 Lua 中通過 host.table(rows, formats) 的指令碼，可以為新列建議數字格式、寬度和對齊方式。你自己的格式始終優先於建議。在同一會話中消失後又重新出現的列會恢復原樣，而新的數字列會右對齊。
試一試
Examples\Formula\Data Sources.xlsx 包含兩個由 =DATASOURCE() 溢位的 Data Source：Sales 是活頁簿旁邊的 SQLite 資料庫 Sales.db，按 Region 參數讀取；Forecast 是 Open-Meteo 在 Latitude 和 Longitude 參數所指位置的一週預報。在被詢問時分別允許它們，然後在 Parameters 面板中更改某個參數：表格會重新取得資料，而每一列都保留其格式。
另請參閱
- 智慧物件
- 依賴關係，展示讀取每個 Data Source 的內容
- 自動化與程式設計模型