Class DataSourceTable

DataSourceTable

访问和修改现有数据源表。要在新的工作表中创建新的数据源表格，请执行以下操作： 请使用 Spreadsheet.insertSheetWithDataSourceTable(spec)。

只能将此类与 BigQuery 数据源搭配使用。

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

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)

向数据源表添加列。

参数

名称类型说明
columnNamesString[]要添加的列名称的列表。

返回

DataSourceTable - 用于链接的数据源表。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

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

addFilter(columnName, filterCriteria)

添加应用于数据源表格的过滤器。

参数

名称类型说明
columnNameString要应用此过滤条件的列的名称。
filterCriteriaFilterCriteria要应用的过滤条件。

返回

DataSourceTable - 用于链接的数据源表。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

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

addSortSpec(columnName, ascending)

向数据源表中的列添加排序规范。

参数

名称类型说明
columnNameString要排序的列的名称。
ascendingBoolean如果为 true，则按升序对此列排序；如果为 false，则按降序对此列排序。

返回

DataSourceTable - 数据源工作表，用于实现链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

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

addSortSpec(columnName, sortOrder)

向数据源表中的列添加排序规范。

参数

名称类型说明
columnNameString要排序的列的名称。
sortOrderSortOrder排序顺序。

返回

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 表格界面中的默认行数上限。

参数

名称类型说明
rowLimitInteger数据表的新行数上限。如果为 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)

等待当前执行完成，在提供的秒数后超时。 如果在超时时未完成执行，则会抛出异常，但不会取消 数据执行。

参数

名称类型说明
timeoutInSecondsInteger等待数据执行的时间，以秒为单位。最大值为 300 。

返回

DataExecutionStatus - 数据执行状态。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

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