Se usó la API de Cloud Translation para traducir esta página.

Usa hojas conectadas

Hojas conectadas es una función de Hojas de cálculo de Google que te permite analizar datos de BigQuery y Looker directamente en Hojas de cálculo. Puedes acceder a Hojas conectadas de forma programática con el servicio de Hojas de cálculo.

Acciones comunes de Hojas conectadas

Usa las clases y los objetos de DataSource para conectarte a BigQuery o Looker y analizar datos. En la siguiente tabla, se enumeran las acciones DataSource más comunes y cómo crearlas en Apps Script:

Acción	Clase de Google Apps Script	Método que se debe usar
Cómo conectar una hoja a una fuente de datos compatible	`DataSourceSpec`	`SpreadsheetApp.newDataSourceSpec()`
Elige una fuente de datos	`DataSource`	`Spreadsheet.insertDataSourceSheet().getDataSource()`
Agrega una hoja de fuente de datos	`DataSourceSheet`	`Spreadsheet.insertDataSourceSheet()`
Cómo agregar una tabla dinámica	`DataSourcePivotTable`	`Range.insertDataSourcePivotTable()`
Extrae datos en un extracto	`DataSourceTable`	`Range.insertDataSourceTable()`
Cómo usar una fórmula	`DataSourceFormula`	`Range.setFormula()`
Add a chart	`DataSourceChart`	`Sheet.insertDataSourceChart()`

Agrega los permisos de autorización necesarios

Para acceder a los datos de BigQuery, debes incluir el método enableBigQueryExecution() en tu código de Google Apps Script. Este método agrega el permiso de OAuth bigquery.readonly requerido a tu proyecto de Google Apps Script.

En el siguiente ejemplo, se muestra el método SpreadsheetApp.enableBigQueryExecution() que se llama dentro de una función:

function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

Para acceder a los datos de Looker, debes incluir el método enableLookerExecution() en tu código de Google Apps Script. Si accedes a Looker en Apps Script, se reutilizará la vinculación existente de tu Cuenta de Google con Looker.

En el siguiente ejemplo, se muestra el método SpreadsheetApp.enableLookerExecution() que se llama dentro de una función:

function addDataSource() {
  SpreadsheetApp.enableLookerExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

Agrega permisos de OAuth adicionales al archivo de manifiesto

Cuando te conectas con BigQuery, la mayoría de los permisos de OAuth se agregan automáticamente al archivo de manifiesto según las funciones que se usan en tu código. Si necesitas permisos adicionales para acceder a ciertos datos de BigQuery, puedes configurar permisos explícitos.

Por ejemplo, para consultar datos de BigQuery alojados en Google Drive, debes agregar un permiso de OAuth de Drive a tu archivo de manifiesto.

En el siguiente ejemplo, se muestra la parte oauthScopes de un archivo de manifiesto. Agrega un permiso de OAuth de Drive además de los permisos de OAuth mínimos requeridos de spreadsheet y bigquery.readonly:

{ ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/bigquery.readonly",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive" ],
... }

Ejemplo: Crea y actualiza un objeto de fuente de datos

En los siguientes ejemplos, se muestra cómo agregar una fuente de datos, crear un objeto de fuente de datos a partir de ella, actualizarlo y obtener el estado de ejecución.

Add a data source

En los siguientes ejemplos, se muestra cómo agregar una fuente de datos de BigQuery y una de Looker, respectivamente.

BigQuery

Para agregar una fuente de datos de BigQuery a una hoja de cálculo, inserta una hoja de fuente de datos con una especificación de fuente de datos. La hoja de fuente de datos se actualiza automáticamente para recuperar datos de vista previa.

Reemplaza <YOUR_PROJECT_ID> a continuación por un ID de proyecto de Google Cloud válido.

// For operations that fetch data from BigQuery, enableBigQueryExecution() must be called.
SpreadsheetApp.enableBigQueryExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asBigQuery()
    .setProjectId('<YOUR_PROJECT_ID>')
    .setTableProjectId('bigquery-public-data')
    .setDatasetId('ncaa_basketball')
    .setTableId('mbb_historical_tournament_games')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Looker

Para agregar una fuente de datos de Looker a una hoja de cálculo, inserta una hoja de fuente de datos con una especificación de fuente de datos. La hoja de fuente de datos se actualiza automáticamente para recuperar datos de vista previa.

Reemplaza <INSTANCE_URL>,<MODEL_NAME>, <EXPLORE_NAME> en el siguiente ejemplo por una URL de instancia de Looker, un nombre de modelo y un nombre de exploración válidos, respectivamente.

// For operations that fetch data from Looker, enableLookerExecution() must be called.
SpreadsheetApp.enableLookerExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asLooker()
    .setInstanceUrl('<INSTANCE_URL>')
    .setModelName('<MODEL_NAME>')
    .setExploreName('<EXPLORE_NAME>')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Agrega un objeto de fuente de datos

Una vez que se agrega la fuente de datos a la hoja de cálculo, se pueden crear objetos de fuente de datos a partir de ella. En este ejemplo, se crea una tabla dinámica con DataSourcePivotTable en el dataSource de BigQuery creado en la muestra de código que agrega un origen de datos de BigQuery.

A diferencia de los datos normales en las hojas de cuadrícula a los que se hace referencia por índice de celda o notaciones A1, a los datos de las fuentes de datos, por lo general, se hace referencia por nombres de columna. Por lo tanto, la mayoría de los set de propiedades en objetos de fuente de datos usan el nombre de la columna como entrada.

var rootCell = spreadsheet.insertSheet('pivotTableSheet').getRange('A1');

// Add data source pivot table and set data source specific configurations.
var dataSourcePivotTable = rootCell.createDataSourcePivotTable(dataSource);
var rowGroup = dataSourcePivotTable.addRowGroup('season');
rowGroup.sortDescending().setGroupLimit(5);
dataSourcePivotTable.addColumnGroup('win_school_ncaa');
dataSourcePivotTable.addPivotValue('win_pts', SpreadsheetApp.PivotTableSummarizeFunction.AVERAGE);
dataSourcePivotTable.addPivotValue('game_date', SpreadsheetApp.PivotTableSummarizeFunction.COUNTA);
var filterCriteria = SpreadsheetApp.newFilterCriteria()
    .whenTextEqualToAny(['Duke', 'North Carolina'])
    .build();
dataSourcePivotTable.addFilter('win_school_ncaa', filterCriteria);

// Get a regular pivot table instance and set shared configurations.
var pivotTable = dataSourcePivotTable.asPivotTable();
pivotTable.setValuesDisplayOrientation(SpreadsheetApp.Dimension.ROWS);

Actualiza un objeto de fuente de datos

Puedes actualizar los objetos de fuente de datos para recuperar los datos más recientes de BigQuery según las especificaciones de la fuente de datos y la configuración de los objetos.

El proceso para actualizar los datos es asíncrono. Para actualizar un objeto de fuente de datos, usa los siguientes métodos:

refreshData() inicia la ejecución de la actualización de datos.
waitForCompletion() muestra el estado final una vez que se completa la ejecución de datos. Esto elimina la necesidad de seguir sondeando el estado de ejecución.
DataExecutionStatus.getErrorCode() obtiene el código de error en caso de que falle la ejecución de datos.

En el siguiente ejemplo, se ilustra una actualización de los datos de la tabla dinámica:

var status = dataSourcePivotTable.getStatus();
Logger.log('Initial state: %s', status.getExecutionState());

dataSourcePivotTable.refreshData();

status = dataSourcePivotTable.waitForCompletion(/* timeoutInSeconds= */ 60);
Logger.log('Ending state: %s', status.getExecutionState());
if (status.getExecutionState() == SpreadsheetApp.DataExecutionState.ERROR) {
  Logger.log('Error: %s (%s)', status.getErrorCode(), status.getErrorMessage());
}

Usa activadores con Hojas conectadas

Automatiza las funciones de tu fuente de datos de Hojas conectadas con activadores y eventos. Por ejemplo, usa activadores basados en el tiempo para actualizar objetos de fuentes de datos de forma reiterada en un momento específico y usa activadores de eventos de hojas de cálculo para activar la ejecución de datos en un evento predefinido.

En el siguiente ejemplo, se agrega una fuente de datos de BigQuery con un parámetro de consulta y se actualiza la hoja de la fuente de datos cuando se edita el parámetro de consulta.

Reemplaza <YOUR_PROJECT_ID> por un ID de proyecto de Google Cloud válido.

// Add data source with query parameter.
function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();

  // Add a new sheet and use A1 cell as the parameter cell.
  var parameterCell = spreadsheet.insertSheet('parameterSheet').getRange('A1');
parameterCell.setValue('Duke');

  // Add data source with query parameter.
  var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
      .asBigQuery()
      .setProjectId('<YOUR_PROJECT_ID>')
      .setRawQuery('select * from `bigquery-public-data`.`ncaa_basketball`.`mbb_historical_tournament_games` WHERE win_school_ncaa = @SCHOOL')
      .setParameterFromCell('SCHOOL', 'parameterSheet!A1')
      .build();
  var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
  dataSourceSheet.asSheet().setName('ncaa_data');
}

// Function used to configure event trigger to refresh data source sheet.
function refreshOnParameterEdit(e) {
  var editedRange = e.range;
if (editedRange.getSheet().getName() != 'parameterSheet') {
  return;
}
// Check that the edited range includes A1.
if (editedRange.getRow() > 1 || editedRange.getColumn() > 1) {
   return;
}

  var spreadsheet = e.source;
  SpreadsheetApp.enableBigQueryExecution();
  spreadsheet.getSheetByName('ncaa_data').asDataSourceSheet().refreshData();
}

En el ejemplo anterior, la función addDataSource() agrega una fuente de datos a la hoja de cálculo. Después de ejecutar addDataSource(), crea un activador de eventos en el editor de Apps Script. Para obtener información sobre cómo crear un activador de eventos, consulta Activadores instalables.

Selecciona las siguientes opciones para tu activador:

Fuente del evento: Desde una hoja de cálculo
Tipo de evento: Al editar
Función para ejecutar: refreshOnParameterEdit

Una vez que se crea el activador, la hoja de la fuente de datos se actualiza automáticamente cada vez que se edita la celda del parámetro.

Solucionar problemas

Mensaje de error Solución

Usa enableBigQuery() para habilitar las ejecuciones de datos de fuentes de datos de BIGQUERY. Este error indica que no se llama a SpreadsheetApp.enableBigQueryExecution() antes de recuperar datos de BigQuery.
Llama a SpreadsheetApp.enableBigQueryExecution() en funciones que usan métodos para la ejecución de BigQuery.
Por ejemplo, refreshData() en objetos de fuentes de datos, Spreadsheet.insertDataSourceTable() y DataSource.updateSpec().
Estos métodos requieren un permiso de OAuth adicional de bigquery.readonly para funcionar.

No tienes permiso para tomar medidas en fuentes de datos.
Comunícate con tu administrador para habilitar la función. Este error indica que la cuenta no tiene habilitadas las Hojas conectadas.
Las Hojas conectadas solo están disponibles para usuarios con ciertas suscripciones.
Comunícate con tu administrador para habilitar la función.

Mensaje de error	Solución
Usa `enableBigQuery()` para habilitar las ejecuciones de datos de fuentes de datos de BIGQUERY.	Este error indica que no se llama a `SpreadsheetApp.enableBigQueryExecution()` antes de recuperar datos de BigQuery. Llama a `SpreadsheetApp.enableBigQueryExecution()` en funciones que usan métodos para la ejecución de BigQuery. Por ejemplo, `refreshData()` en objetos de fuentes de datos, `Spreadsheet.insertDataSourceTable()` y `DataSource.updateSpec()`. Estos métodos requieren un permiso de OAuth adicional de bigquery.readonly para funcionar.
No tienes permiso para tomar medidas en fuentes de datos. Comunícate con tu administrador para habilitar la función.	Este error indica que la cuenta no tiene habilitadas las Hojas conectadas. Las Hojas conectadas solo están disponibles para usuarios con ciertas suscripciones. Comunícate con tu administrador para habilitar la función.