Introducción a Google Sheets API

La Google Sheets API te permite leer y modificar cualquier aspecto de una hoja de cálculo. Las hojas de cálculo cuentan con muchas configuraciones que te permiten diseñar hojas hermosas y funcionales, así que la API también ofrece muchas configuraciones. La API ofrece dos formas principales de interactuar con la hoja de cálculo:

Ambas colecciones son fáciles de usar, aunque la colección spreadsheets ofrece muchas más opciones. Para obtener más información sobre estas colecciones y su uso, consulta los vínculos de la documentación de referencia mencionados o las siguientes guías para desarrolladores:

Términos comunes

En esta sección, se explican algunos de los términos que encontrarás cuando leas acerca de la Sheets API.

ID de la hoja de cálculo

Todos los métodos de la API requieren un parámetro spreadsheetId que se utiliza para identificar la hoja de cálculo a la que se accederá o la hoja de cálculo que se modificará. Este ID es el valor entre “/d/” y “/edit” de la URL de tu hoja de cálculo. Por ejemplo, observa la siguiente URL que hace referencia a una hoja de cálculo de Google Sheets:

https://docs.google.com/spreadsheets/d/1qpyC0XzvTcKT6EISywvqESX3A0MwQoFDE8p-Bll4hps/edit#gid=0

El ID de esta hoja de cálculo es 1qpyC0XzvTcKT6EISywvqESX3A0MwQoFDE8p-Bll4hps.

El ID de la hoja de cálculo es un string con letras, números y algunos caracteres especiales. La siguiente expresión regular se puede usar para extraer el ID de la hoja de cálculo de una URL de Google Sheets.

/spreadsheets/d/([a-zA-Z0-9-_]+)

Si conoces la Drive API, spreadsheet_id corresponde al ID del recurso File.

ID de la hoja

En una hoja de cálculo, cada hoja tiene un título (que debe ser único) y un ID. sheetId se usa frecuentemente en la Sheets API para especificar la hoja que se está leyendo o actualizando. En la IU de Sheets, puedes encontrar el sheetId de la hoja abierta en la URL de la hoja de cálculo, que aparece como el valor del parámetro gid. A continuación, se muestra la estructura de la URL y la ubicación de sheetId:

https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=sheetId

El ID de la hoja es numérico y se puede usar la siguiente expresión regular para extraerlo de una URL de Google Sheets.

[#&]gid=([0-9]+)

También puedes obtener el ID de las hojas si utilizas la API; consulta el ejemplo de Determinar el ID de la hoja y otras propiedades.

Notación A1

Algunos métodos de la API requieren que los rangos estén en notación A1. Es un string como Sheet1!A1:B2, que hace referencia a un grupo de celdas en la hoja de cálculo y se usa generalmente en fórmulas. Por ejemplo, estos son rangos válidos:

  • Sheet1!A1:B2 hace referencia a las primeras dos celdas en las primeras dos filas de Sheet1.
  • Sheet1!A:A hace referencia a todas las celdas en la primera columna de Sheet1.
  • Sheet1!1:2 hace referencia a todas las celdas en las primeras dos filas de Sheet1.
  • Sheet1!A5:A hace referencia a todas las celdas en la primera columna de Sheet1, a partir de la fila 5.
  • A1:B2 hace referencia a las primeras dos celdas en las primeras dos filas de la primera hoja visible.
  • Sheet1 hace referencia a todas las celdas de Sheet1.

También se admiten rangos con nombre. Cuando un rango con nombre entra en conflicto con el nombre de una hoja, se da prioridad al rango con nombre.

Números en serie para fecha/hora

En Google Sheets, como en la mayoría de las aplicaciones de hojas de cálculo, se considera a los valores de fecha/hora como valores decimales. De esta forma, puedes realizar operaciones aritméticas con estos valores mediante fórmulas: puedes incrementar los días o las semanas, sumar o restar dos fechas/horas, y realizar otras operaciones similares.

Google Sheets usa un tipo de fecha epoch que se usa frecuentemente en hojas de cálculo. La porción de número entero del valor (a la izquierda del decimal) cuenta los días desde el 30 de diciembre de 1899. La porción fraccionaria (a la derecha del decimal) cuenta el tiempo como una fracción de un día. Por ejemplo, el 1 de enero de 1900 al mediodía sería 2.5, 2 porque se cuentan dos días después del 30 de diciembre de 1899 y .5 porque el mediodía es la mitad de un día. El 1 de febrero de 1900 a las 3:00 p.m. sería 33.625.

Observa que Google Sheets considera correctamente a 1900 como un año normal y no uno bisiesto.

Respuestas parciales

Las hojas de cálculo son grandes y, a menudo, no necesitas todas sus partes. Con el parámetro fields, puedes limitar lo que mostrará la respuesta de la Google Sheets API. Será particularmente útil en el método spreadsheets.get. Para lograr el máximo rendimiento, enumera de forma explícita solo los campos que necesites en la respuesta. El formato del parámetro fields es igual a la codificación JSON de una FieldMask. En resumen, varios campos diferentes se separan con comas y los subcampos se separan con puntos. Para una mayor practicidad, varios subcampos del mismo tipo pueden listarse entre paréntesis.

Por ejemplo, para recuperar el título de la hoja de cálculo, las propiedades de la hoja, y el valor y el formato del rango A1:C10, puedes usar la siguiente solicitud:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?ranges=A1:C10&fields=properties.title,sheets(sheetProperties,data.rowData.values(effectiveValue,effectiveFormat))

Enviar comentarios sobre…