Hojas conectadas

Hojas conectadas te permite analizar petabytes de datos directamente en Hojas de cálculo de Google. Puedes conectar tus hojas de cálculo con un almacén de datos de BigQuery o Looker y realizar el análisis con herramientas conocidas de Hojas de cálculo, como tablas dinámicas, gráficos y fórmulas.

Administra una fuente de datos de BigQuery

En esta sección, se usa el conjunto de datos públicos de BigQuery Shakespeare para mostrar cómo usar Hojas conectadas. El conjunto de datos contiene la siguiente información:

Campo Tipo Descripción
palabra STRING Es una sola palabra única (en la que el espacio en blanco es el delimitador) extraída de un corpus.
word_count INTEGER Es la cantidad de veces que aparece esta palabra en este corpus.
corpus STRING Es la obra de la que se extrajo esta palabra.
corpus_date INTEGER Año en el que se publicó este corpus.

Si tu aplicación solicita datos de Hojas conectadas de BigQuery, debe proporcionar un token de OAuth 2.0 que otorgue el alcance bigquery.readonly, además de los otros alcances necesarios para una solicitud normal a la API de Hojas de cálculo de Google. Para obtener más información, consulta Cómo elegir los alcances de la API de Google Sheets.

Una fuente de datos especifica una ubicación externa en la que se encuentran los datos. Luego, la fuente de datos se conecta a la hoja de cálculo.

Agrega una fuente de datos de BigQuery

Para agregar una fuente de datos, proporciona un AddDataSourceRequest con el método spreadsheets.batchUpdate. El cuerpo de la solicitud debe especificar un campo dataSource de tipo objeto DataSource.

"addDataSource":{    "dataSource":{       "spec":{          "bigQuery":{             "projectId":"PROJECT_ID",             "tableSpec":{                "tableProjectId":"bigquery-public-data",                "datasetId":"samples",                "tableId":"shakespeare"             }          }       }    } }

Reemplaza PROJECT_ID por un ID del proyecto de Google Cloud válido.

Después de crear una fuente de datos, se crea una hoja de DATA_SOURCE asociada para proporcionar una vista previa de hasta 500 filas. La vista previa no está disponible de inmediato. Se activa una ejecución de forma asíncrona para importar los datos de BigQuery.

El objeto AddDataSourceResponse contiene los siguientes campos:

  • dataSource: Es el objeto DataSource creado. El dataSourceId es un ID único con alcance de hoja de cálculo. Se completa y se hace referencia a él para crear cada objeto DataSource de la fuente de datos.

  • dataExecutionStatus: Es el estado de una ejecución que importa datos de BigQuery a la hoja de vista previa. Para obtener más información, consulta la sección Estado de ejecución de los datos.

Actualiza o borra una fuente de datos de BigQuery

Usa el método spreadsheets.batchUpdate y proporciona una solicitud UpdateDataSourceRequest o DeleteDataSourceRequest según corresponda.

Administra objetos de fuentes de datos de BigQuery

Una vez que se agrega una fuente de datos a la hoja de cálculo, se puede crear un objeto de fuente de datos a partir de ella. Un objeto de fuente de datos es una herramienta normal de Hojas de cálculo, como tablas dinámicas, gráficos y fórmulas, que se integra con las Hojas conectadas para potenciar tu análisis de datos.

Existen cuatro tipos de objetos:

  • DataSource tabla
  • DataSource pivotTable
  • Gráfico de DataSource
  • Fórmula DataSource

Agrega una tabla de fuente de datos de BigQuery

Conocido como "extracción" en el editor de Hojas de cálculo, el objeto de tabla importa un volcado estático de datos de la fuente de datos a Hojas de cálculo. Al igual que una tabla dinámica, la tabla se especifica y se ancla a la celda superior izquierda.

En el siguiente ejemplo de código, se muestra cómo usar el método spreadsheets.batchUpdate y un UpdateCellsRequest para crear una tabla de fuentes de datos con hasta 1,000 filas de dos columnas (word y word_count).

"updateCells":{    "rows":{       "values":[          {             "dataSourceTable":{                "dataSourceId":"DATA_SOURCE_ID",                "columns":[                   {                      "name":"word"                   },                   {                      "name":"word_count"                   }                ],                "rowLimit":{                   "value":1000                },                "columnSelectionType":"SELECTED"             }          }       ]    },    "fields":"dataSourceTable" }

Reemplaza DATA_SOURCE_ID por un ID único con alcance de hoja de cálculo que identifique la fuente de datos.

Después de crear una tabla de fuentes de datos, los datos no están disponibles de inmediato. En el editor de Hojas de cálculo, se muestra como vista previa. Debes actualizar la tabla de la fuente de datos para recuperar los datos de BigQuery. Puedes especificar un RefreshDataSourceRequest dentro del mismo batchUpdate. Ten en cuenta que todos los objetos de fuente de datos funcionan de manera similar. Para obtener más información, consulta Cómo actualizar un objeto de fuente de datos.

Una vez que se completa la actualización y se recuperan los datos de BigQuery, se completa la tabla de la fuente de datos, como se muestra a continuación:

Tabla de la fuente de datos que muestra datos del conjunto de datos públicos de Shakespeare.

Agrega una tabla dinámica de la fuente de datos de BigQuery

A diferencia de una tabla dinámica convencional, una tabla dinámica de fuente de datos se basa en una fuente de datos y hace referencia a los datos por nombre de columna. En el siguiente ejemplo de código, se muestra cómo usar el método spreadsheets.batchUpdate y un objeto UpdateCellsRequest para crear una tabla dinámica que muestre el recuento total de palabras por corpus.

"updateCells":{    "rows":{       "values":[          {             "pivotTable":{                "dataSourceId":"DATA_SOURCE_ID",                "rows":{                   "dataSourceColumnReference":{                      "name":"corpus"                   },                   "sortOrder":"ASCENDING"                },                "values":{                   "summarizeFunction":"SUM",                   "dataSourceColumnReference":{                      "name":"word_count"                   }                }             }          }       ]    },    "fields":"pivotTable"     }

Reemplaza DATA_SOURCE_ID por un ID único con alcance de hoja de cálculo que identifique la fuente de datos.

Después de recuperar los datos de BigQuery, se completará la tabla dinámica de la fuente de datos como se muestra a continuación:

Tabla dinámica de la fuente de datos que muestra datos del conjunto de datos públicos de Shakespeare.

Agrega un gráfico de fuente de datos de BigQuery

En la siguiente muestra de código, se muestra cómo usar el método spreadsheets.batchUpdate y un AddChartRequest para crear un gráfico de fuente de datos con un chartType de COLUMN, que muestra el recuento total de palabras por corpus.

"addChart":{    "chart":{       "spec":{          "title":"Corpus by word count",          "basicChart":{             "chartType":"COLUMN",             "domains":[                {                   "domain":{                      "columnReference":{                         "name":"corpus"                      }                   }                }             ],             "series":[                {                   "series":{                      "columnReference":{                         "name":"word_count"                      },                      "aggregateType":"SUM"                   }                }             ]          }       },       "dataSourceChartProperties":{          "dataSourceId":"DATA_SOURCE_ID"       }    } }

Reemplaza DATA_SOURCE_ID por un ID único con alcance de hoja de cálculo que identifique la fuente de datos.

Después de recuperar los datos de BigQuery, se renderiza el gráfico de la fuente de datos, como se muestra a continuación:

Gráfico de la fuente de datos que muestra datos del conjunto de datos públicos de Shakespeare.

Agrega una fórmula de fuente de datos de BigQuery

En el siguiente ejemplo de código, se muestra cómo usar el método spreadsheets.batchUpdate y un UpdateCellsRequest para crear una fórmula de fuente de datos que calcule el recuento promedio de palabras.

"updateCells":{    "rows":[       {          "values":[             {                "userEnteredValue":{                   "formulaValue":"=AVERAGE(shakespeare!word_count)"                }             }          ]       }    ],    "fields":"userEnteredValue" }

Después de recuperar los datos de BigQuery, la fórmula de la fuente de datos se completará como se muestra a continuación:

Fórmula de fuente de datos que muestra datos del conjunto de datos públicos de Shakespeare.

Actualiza un objeto de fuente de datos de BigQuery

Puedes actualizar un objeto 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 del objeto actuales. Puedes usar el método spreadsheets.batchUpdate para llamar a RefreshDataSourceRequest. Luego, especifica una o más referencias de objetos para actualizar con el objeto DataSourceObjectReferences.

Ten en cuenta que puedes crear y actualizar objetos de fuentes de datos en una sola solicitud de batchUpdate.

Administra una fuente de datos de Looker

En esta guía, se mostrará cómo agregar, actualizar o borrar una fuente de datos de Looker, crear una tabla dinámica en ella y actualizarla.

Tu aplicación que solicite datos de Hojas conectadas de Looker reutilizará tu vinculación existente de la Cuenta de Google con Looker.

Agrega una fuente de datos de Looker

Para agregar una fuente de datos, proporciona un AddDataSourceRequest con el método spreadsheets.batchUpdate. El cuerpo de la solicitud debe especificar un campo dataSource de tipo objeto DataSource.

"addDataSource":{    "dataSource":{       "spec":{          "looker":{             "instance_uri":"INSTANCE_URI",             "model":"MODEL",             "explore":"EXPLORE"          }       }    } }

Reemplaza INSTANCE_URI, MODEL y EXPLORE por un URI de instancia de Looker, un nombre de modelo y un nombre de Explore válidos, respectivamente.

Después de crear una fuente de datos, se crea una hoja de cálculo asociada de DATA_SOURCE para proporcionar una vista previa de la estructura de la función Explorar seleccionada, incluidas las vistas, las dimensiones, las medidas y las descripciones de los campos.

El objeto AddDataSourceResponse contiene los siguientes campos:

  • dataSource: Es el objeto DataSource creado. El dataSourceId es un ID único con alcance de hoja de cálculo. Se propaga y se hace referencia a él para crear cada objeto DataSource a partir de la fuente de datos.

  • dataExecutionStatus: Es el estado de una ejecución que importa datos de BigQuery a la hoja de vista previa. Para obtener más información, consulta la sección Estado de ejecución de los datos.

Actualiza o borra una fuente de datos de Looker

Usa el método spreadsheets.batchUpdate y proporciona una solicitud UpdateDataSourceRequest o DeleteDataSourceRequest según corresponda.

Administra objetos de fuentes de datos de Looker

Una vez que se agrega una fuente de datos a la hoja de cálculo, se puede crear un objeto de fuente de datos a partir de ella. En el caso de las fuentes de datos de Looker, solo puedes crear un objeto DataSourcepivotTable a partir de ellas.

No es posible crear fórmulas, extracciones ni gráficos de DataSource a partir de fuentes de datos de Looker.

Actualiza un objeto de fuente de datos de Looker

Puedes actualizar un objeto de fuente de datos para recuperar los datos más recientes de Looker según las especificaciones de la fuente de datos y las configuraciones de objetos actuales. Puedes usar el método spreadsheets.batchUpdate para llamar a RefreshDataSourceRequest. Luego, especifica una o más referencias de objetos para actualizar con el objeto DataSourceObjectReferences.

Ten en cuenta que puedes crear y actualizar objetos de fuentes de datos en una sola solicitud de batchUpdate.

Estado de ejecución de datos

Cuando creas fuentes de datos o actualizas objetos de fuentes de datos, se crea una ejecución en segundo plano para recuperar los datos de BigQuery o Looker y devolver una respuesta que contiene el DataExecutionStatus. Si la ejecución se inicia correctamente, el objeto DataExecutionState suele estar en el estado RUNNING.

Como el proceso es asíncrono, tu aplicación debe implementar un modelo de sondeo para recuperar periódicamente el estado de los objetos de la fuente de datos. Usa el método spreadsheets.get hasta que el estado devuelva el estado SUCCEEDED o FAILED. En la mayoría de los casos, la ejecución se completa rápidamente, pero depende de la complejidad de tu fuente de datos. Por lo general, la ejecución no supera los 10 minutos.