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 BigQuery de BigQuery o Looker, y realizar el análisis con las herramientas familiares 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 Shakespeare públicos de BigQuery para mostrar cómo usar Hojas conectadas. El conjunto de datos contiene la siguiente información:

Campo Tipo Descripción
palabra STRING Una sola palabra única (donde el espacio en blanco es el delimitador) extraída de un corpus
word_count INTEGER La cantidad de veces que aparece esta palabra en este corpus
corpus STRING El trabajo del que se extrajo esta palabra
corpus_date INTEGER El año en 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 de la API de Google Sheets. Para obtener más información, consulta Elige los alcances de la API de Google Sheets scopes.

Una fuente de datos especifica una ubicación externa donde 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 DataSource objeto.

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

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

Después de crear una fuente de datos, se crea una hoja asociada DATA_SOURCE 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.

AddDataSourceResponse contiene los siguientes campos:

  • dataSource: 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: 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 datos.

Actualiza o borra una fuente de datos de BigQuery

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

Administra objetos de fuente 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 Hojas conectadas para potenciar el análisis de datos.

Existen los siguientes cuatro tipos de objetos:

  • Tabla DataSource
  • DataSource pivotTable
  • Gráfico DataSource
  • Fórmula DataSource

Agrega una tabla de fuente de datos de BigQuery

Conocido como "extracto" 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 la siguiente muestra de código, se muestra cómo usar el spreadsheets.batchUpdate y un UpdateCellsRequest para crear una tabla de fuente de datos de 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 fuente de datos, los datos no están disponibles de inmediato. En el editor de Hojas de cálculo, se muestra como una vista previa. Debes actualizar la tabla de 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 Actualiza un objeto de fuente de datos.

Una vez que se completa la actualización y se recuperan los datos de BigQuery, la tabla de fuente de datos se propaga 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 fuente de datos de BigQuery

A diferencia de una tabla dinámica convencional, una tabla dinámica de fuente de datos está respaldada por una fuente de datos y hace referencia a los datos por nombre de columna. En la siguiente muestra de código, se muestra cómo usar el método spreadsheets.batchUpdate y un 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.

Una vez que se recuperan los datos de BigQuery, la tabla dinámica de fuente de datos se propaga 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.

Una vez que se recuperan los datos de BigQuery, el gráfico de fuente de datos se renderiza 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 la siguiente muestra 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 para calcular el recuento promedio de palabras.

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

Una vez que se recuperan los datos de BigQuery, la fórmula de fuente de datos se propaga como se muestra a continuación:

Fórmula de la 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 en función de las especificaciones de la fuente de datos actual y las configuraciones de objetos. Puedes usar el spreadsheets.batchUpdate método para llamar a RefreshDataSourceRequest. Luego, especifica una o más referencias de objetos para actualizar con el DataSourceObjectReferences objeto.

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

Administra una fuente de datos de Looker

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

Tu aplicación que solicite datos de Hojas conectadas de Looker reutilizará tu vínculo 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 DataSource objeto.

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

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

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

AddDataSourceResponse contiene los siguientes campos:

  • dataSource: 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: 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 datos.

Actualiza o borra una fuente de datos de Looker

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

Administra objetos de fuente 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. Para las fuentes de datos de Looker, solo puedes crear un objeto DataSource pivotTable a partir de ella.

No es posible crear fórmulas, extractos ni gráficos 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 en función de las especificaciones de la fuente de datos actual y las configuraciones de objetos. Puedes usar el spreadsheets.batchUpdate método para llamar a RefreshDataSourceRequest. Luego, especifica una o más referencias de objetos para actualizar con el DataSourceObjectReferences objeto.

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

Estado de ejecución de datos

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

Debido a que el proceso es asíncrono, tu aplicación debe implementar un modelo de sondeo para recuperar periódicamente el estado de los objetos de fuente de datos. Usa el spreadsheets.get método hasta que el estado muestre 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 la fuente de datos. Por lo general, la ejecución no supera los 10 minutos.