本頁面由 Cloud Translation API 翻譯而成。

Class DataSourceTable

存取及修改現有的資料來源資料表。如要在新工作表中建立新的資料來源資料表，請使用 Spreadsheet.insertSheetWithDataSourceTable(spec)。

請只搭配已連線至資料庫的資料使用此類別。

本例顯示如何建立新的資料來源資料表。

SpreadsheetApp.enableBigQueryExecution();
var spreadsheet = SpreadsheetApp.getActive();
var spec = SpreadsheetApp.newDataSourceSpec()
           .asBigQuery()
           .setProjectId('big_query_project')
           .setRawQuery('select @FIELD from table limit @LIMIT')
           .setParameterFromCell('FIELD', 'Sheet1!A1')
           .setParameterFromCell('LIMIT', 'namedRangeCell')
           .build();
// Starts data execution asynchronously.
var dataSheet = spreadsheet.insertSheetWithDataSourceTable(spec);
var dataSourceTable = dataSheet.getDataSourceTables()[0];
// waitForCompletion() blocks script execution until data execution completes.
dataSourceTable.waitForCompletion(60);
// Check status after execution.
Logger.log("Data execution state: %s.", dataSourceTable.getStatus().getExecutionState());

本例顯示如何編輯資料來源。

SpreadsheetApp.enableBigQueryExecution();
var dataSheet = SpreadsheetApp.getActive().getSheetByName("Data Sheet 1");
var dataSourceTable = dataSheet.getDataSourceTables()[0];
var dataSource = dataSourceTable.getDataSource();
var newSpec = dataSource.getSpec()
              .copy()
              .asBigQuery()
              .setRawQuery('select name from table limit 2')
              .removeAllParameters()
              .build();
// Updates data source specification and starts data execution asynchronously.
dataSource.updateSpec(newSpec);
// Check status during execution.
Logger.log("Data execution state: %s.", dataSourceTable.getStatus().getExecutionState());
// waitForCompletion() blocks script execution until data execution completes.
dataSourceTable.waitForCompletion(60);
// Check status after execution.
Logger.log("Data execution state: %s.", dataSourceTable.getStatus().getExecutionState());

方法

方法	傳回類型	簡短說明
`addColumns(columnNames)`	`DataSourceTable`	在資料來源資料表中新增資料欄。
`addFilter(columnName, filterCriteria)`	`DataSourceTable`	新增套用至資料來源資料表的篩選器。
`addSortSpec(columnName, ascending)`	`DataSourceTable`	為資料來源資料表中的資料欄新增排序規格。
`addSortSpec(columnName, sortOrder)`	`DataSourceTable`	為資料來源資料表中的資料欄新增排序規格。
`cancelDataRefresh()`	`DataSourceTable`	如果這個物件正在執行中，則取消相關的資料重新整理作業。
`forceRefreshData()`	`DataSourceTable`	重新整理這個物件的資料，無論目前狀態為何。
`getColumns()`	`DataSourceTableColumn[]`	取得已新增至資料來源資料表的所有資料來源欄。
`getDataSource()`	`DataSource`	取得物件連結的資料來源。
`getFilters()`	`DataSourceTableFilter[]`	傳回已套用到資料來源資料表的所有篩選器。
`getRange()`	`Range`	取得這個資料來源資料表時距的 `Range`。
`getRowLimit()`	`Integer`	傳回資料來源資料表的資料列限制。
`getSortSpecs()`	`SortSpec[]`	取得資料來源表格中的所有排序規格。
`getStatus()`	`DataExecutionStatus`	取得物件的資料執行狀態。
`isSyncingAllColumns()`	`Boolean`	傳回資料來源資料表是否同步處理關聯資料來源中的所有資料欄。
`refreshData()`	`DataSourceTable`	重新整理物件資料。
`removeAllColumns()`	`DataSourceTable`	移除資料來源資料表中的所有資料欄。
`removeAllSortSpecs()`	`DataSourceTable`	移除資料來源表格中的所有排序規格。
`setRowLimit(rowLimit)`	`DataSourceTable`	更新資料來源資料表的資料列限制。
`syncAllColumns()`	`DataSourceTable`	將相關資料來源中現有和日後的所有資料欄同步到資料來源資料表。
`waitForCompletion(timeoutInSeconds)`	`DataExecutionStatus`	等到目前的執行作業完成，並在指定的秒數過後逾時。

內容詳盡的說明文件

`addColumns(columnNames)`

在資料來源資料表中新增資料欄。

參數

名稱	類型	說明
`columnNames`	`String[]`	列出要新增的資料欄名稱。

回攻員

DataSourceTable：用於鏈結的資料來源資料表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`addFilter(columnName, filterCriteria)`

新增套用至資料來源資料表的篩選器。

參數

名稱	類型	說明
`columnName`	`String`	要套用此篩選器的資料欄名稱。
`filterCriteria`	`FilterCriteria`	要套用的篩選條件。

回攻員

DataSourceTable：用於鏈結的資料來源資料表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`addSortSpec(columnName, ascending)`

為資料來源資料表中的資料欄新增排序規格。

參數

名稱	類型	說明
`columnName`	`String`	要排序的資料欄名稱。
`ascending`	`Boolean`	如果是 `true`，請以遞增順序排序資料欄；如果為 `false`，則以遞減方式排序資料欄。

回攻員

DataSourceTable：用於鏈結的資料來源工作表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`addSortSpec(columnName, sortOrder)`

為資料來源資料表中的資料欄新增排序規格。

參數

名稱	類型	說明
`columnName`	`String`	要排序的資料欄名稱。
`sortOrder`	`SortOrder`	排列順序。

回攻員

DataSourceTable：用於鏈結的資料來源工作表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`cancelDataRefresh()`

如果這個物件正在執行中，則取消相關的資料重新整理作業。

以下範例說明如何取消公式重新整理作業。

const spreadsheet = SpreadsheetApp.getActive();
const formula = spreadsheet.getDataSourceFormulas()[0];
// Cancel the ongoing refresh on the formula.
formula.cancelDataRefresh();

如果未啟用資料來源類型，就會擲回例外狀況。使用 SpreadsheetApp#enable...Execution() 方法即可為特定資料來源類型啟用資料執行功能。

回攻員

DataSourceTable：資料物件。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`forceRefreshData()`

重新整理這個物件的資料，無論目前狀態為何。詳情請參閱 refreshData()。如要取消這個物件目前正在執行的重新整理作業，請參閱 cancelDataRefresh()。

如果未啟用資料來源類型，就會擲回例外狀況。使用 SpreadsheetApp#enable...Execution() 方法即可為特定資料來源類型啟用資料執行功能。

回攻員

DataSourceTable：資料物件。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getColumns()`

取得已新增至資料來源資料表的所有資料來源欄。

回攻員

DataSourceTableColumn[]：資料來源資料表的資料欄清單。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getDataSource()`

取得物件連結的資料來源。

回攻員

DataSource：資料來源。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getFilters()`

傳回已套用到資料來源資料表的所有篩選器。

回攻員

DataSourceTableFilter[]：套用至資料來源資料表的所有篩選器陣列。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getRange()`

取得這個資料來源資料表時距的 Range。

回攻員

Range：範圍。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getRowLimit()`

傳回資料來源資料表的資料列限制。

回攻員

Integer：資料來源資料表的資料列限制；如未設定限制，則資料表會使用與 Google 試算表 UI 相同的預設上限。null

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getSortSpecs()`

取得資料來源表格中的所有排序規格。

回攻員

SortSpec[] — 排序規格清單。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getStatus()`

取得物件的資料執行狀態。

回攻員

DataExecutionStatus：資料執行狀態。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`isSyncingAllColumns()`

傳回資料來源資料表是否同步處理關聯資料來源中的所有資料欄。

回攻員

Boolean：如果資料來源資料表同步處理相關聯的資料來源中的所有資料欄，則為 True，否則傳回 false。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`refreshData()`

重新整理物件資料。

如果目前處於 error 狀態，就會擲回例外狀況。使用 DataSource#updateSpec() 更新規格。為避免在資料來源發生未預期的編輯作業，建議採用此方法，而非 forceRefreshData()。

如果未啟用資料來源類型，就會擲回例外狀況。使用 SpreadsheetApp#enable...Execution() 方法即可為特定資料來源類型啟用資料執行功能。

回攻員

DataSourceTable：資料物件。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeAllColumns()`

移除資料來源資料表中的所有資料欄。

回攻員

DataSourceTable：用於鏈結的資料來源資料表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeAllSortSpecs()`

移除資料來源表格中的所有排序規格。

回攻員

DataSourceTable：用於鏈結的資料來源工作表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setRowLimit(rowLimit)`

更新資料來源資料表的資料列限制。如果提供的資料列限制為 null，則更新資料來源資料表，使其使用 Google 試算表 UI 的預設資料列上限。

參數

名稱	類型	說明
`rowLimit`	`Integer`	資料表的新資料列限制。如果是 `null`，系統會將資料表更新為使用預設資料列限制。

回攻員

DataSourceTable：用於鏈結的資料來源資料表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`syncAllColumns()`

將相關資料來源中現有和日後的所有資料欄同步到資料來源資料表。

回攻員

DataSourceTable：用於鏈結的資料來源資料表。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`waitForCompletion(timeoutInSeconds)`

等到目前的執行作業完成，並在指定的秒數過後逾時。如果執行作業在逾時時未完成，但不取消資料執行，就會擲回例外狀況。

參數

名稱	類型	說明
`timeoutInSeconds`	`Integer`	等待資料執行的時間 (以秒為單位)。上限為 300 秒。

回攻員

DataExecutionStatus：資料執行狀態。

授權

如果指令碼使用這個方法，則必須取得下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets