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 de DataSource más comunes y cómo crearlas en Apps Script:

Acción	Clase de Google Apps Script	Método que se usará
Conecta 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()`
Agrega 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 obligatorios

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 alcance de OAuth bigquery.readonly requerido a tu proyecto de Google Apps Script.

En el siguiente ejemplo, se muestra el método SpreadsheetApp.enableBigQueryExecution() llamado 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. Cuando accedas a Looker en Apps Script, se reutilizará tu vinculación existente de la Cuenta de Google con Looker.

En el siguiente ejemplo, se muestra el método SpreadsheetApp.enableLookerExecution() llamado 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 establecer 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 spreadsheet y bigquery.readonly mínimos requeridos:

{ ...
  "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 el siguiente ejemplo, se muestra cómo agregar una fuente de datos, crear un objeto de fuente de datos a partir de la fuente de datos, actualizar el objeto de fuente de datos y obtener el estado de ejecución.

Agrega una fuente de datos

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 los datos de vista previa.

Reemplaza <YOUR_PROJECT_ID> 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 los datos de vista previa.

Reemplaza <INSTANCE_URL>,<MODEL_NAME> y <EXPLORE_NAME> en el siguiente ejemplo por una URL de instancia de Looker, un nombre de modelo y un nombre de Explorar 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 el ejemplo de código que agrega una fuente de datos de BigQuery.

A diferencia de los datos normales en las hojas de cuadrícula a los que se hace referencia por el índice de celda o las notaciones A1, los datos de las fuentes de datos suelen hacer referencia a los nombres de las columnas. Por lo tanto, la mayoría de los establecedores de propiedades en los objetos de la 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 las configuraciones 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() devuelve el estado final una vez que se completa la ejecución de datos. Esto elimina la necesidad de sondear constantemente el estado de la 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 los objetos de la fuente de datos de forma repetida en un momento específico y usa activadores de eventos de la hoja 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 el activador:

Fuente del evento: Desde la 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 llamó a SpreadsheetApp.enableBigQueryExecution() antes de recuperar los datos de BigQuery.
Llama a SpreadsheetApp.enableBigQueryExecution() en las 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 habilitada la función Hojas conectadas.
Hojas conectadas solo está disponible para los usuarios de Google Workspace 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 llamó a `SpreadsheetApp.enableBigQueryExecution()` antes de recuperar los datos de BigQuery. Llama a `SpreadsheetApp.enableBigQueryExecution()` en las 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 habilitada la función Hojas conectadas. Hojas conectadas solo está disponible para los usuarios de Google Workspace con ciertas suscripciones. Comunícate con tu administrador para habilitar la función.

Usa hojas conectadas Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.