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 Shakespeare de BigQuery 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 los espacios en blanco son el delimitador) extraída de un corpus.
word_count INTEGER Es la cantidad de veces que esta palabra aparece en este corpus.
corpus STRING Es la obra de la que se extrajo esta palabra.
corpus_date INTEGER Es 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 permiso bigquery.readonly, además de los otros permisos necesarios para una solicitud normal a la API de Hojas de cálculo de Google. Para obtener más información, consulta Elige los permisos de la API de Hojas de cálculo de Google.

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 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: Es el objeto DataSource creado. dataSourceId es un ID único centrado en la 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 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 está integrada en 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 “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 método 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 centrado en la 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 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, la tabla de la 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 un pivotante 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 centrado en la hoja de cálculo que identifique la fuente de datos.

Después de recuperar los datos de BigQuery, la tabla dinámica de la 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 COLUMNA, que muestra el recuento de palabras total 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 centrado en la hoja de cálculo que identifique la fuente de datos.

Después de recuperar los datos de BigQuery, el gráfico de la fuente de datos se renderiza de la siguiente manera:

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 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 propaga de la siguiente manera:

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 según las especificaciones y configuraciones de objetos de la fuente de datos actual. 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 fuente de datos en una sola solicitud batchUpdate.

Administra una fuente de datos de Looker

En esta guía, se muestra 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 volverá a usar la vinculación de tu Cuenta de Google existente 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 exploración 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: Es el objeto DataSource creado. dataSourceId es un ID único centrado en la 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 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 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. En el caso de las fuentes de datos de Looker, solo puedes crear un objeto DataSource pivotTable a partir de ellas.

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 basados en las especificaciones y configuraciones de objetos actuales de la fuente de datos. 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 fuente de datos en una sola solicitud 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 mostrar una respuesta que contiene el objeto DataExecutionStatus. Si la ejecución se inicia correctamente, 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 la fuente de datos. Usa el método spreadsheets.get hasta que el estado muestre el estado SUCCEEDED o FAILED. La ejecución se completa rápidamente en la mayoría de los casos, pero depende de la complejidad de tu fuente de datos. Por lo general, la ejecución no supera los 10 minutos.