此页面由 Cloud Translation API 翻译。

Class DataSourceTable

访问和修改现有数据源表。如需在新工作表中创建新的数据源表，请使用 Spreadsheet.insertSheetWithDataSourceTable(spec)。

请仅将此类与 BigQuery 数据源搭配使用。

此示例展示了如何创建新的数据源表。

SpreadsheetApp.enableBigQueryExecution();
const spreadsheet = SpreadsheetApp.getActive();
const 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.
const dataSheet = spreadsheet.insertSheetWithDataSourceTable(spec);
const 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();
const dataSheet = SpreadsheetApp.getActive().getSheetByName('Data Sheet 1');
const dataSourceTable = dataSheet.getDataSourceTables()[0];
const dataSource = dataSourceTable.getDataSource();
const 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 表格界面中的默认上限，则为 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 表格界面中的默认行数上限。

参数

名称	类型	说明
`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