Documentación: Acción Google Sheets¶

Descripción General¶

La Acción Google Sheets es un nodo de automatización que permite interactuar con hojas de cálculo de Google Sheets directamente desde tus automatizaciones. Puedes leer datos, escribir datos, crear hojas, eliminar contenido y realizar diversas operaciones en tus hojas de cálculo de forma automática.

¿Cuándo usar esta acción?¶

Utiliza esta acción cuando necesites: - Registrar datos automáticamente en hojas de cálculo (logs, eventos, métricas) - Leer datos de hojas de cálculo para usarlos en otras acciones - Actualizar registros existentes basándose en condiciones - Crear reportes automáticos en formato de hoja de cálculo - Sincronizar datos entre sistemas y Google Sheets - Gestionar hojas (crear, eliminar, limpiar) de forma programática

Requisitos Previos¶

Antes de usar esta acción, necesitas:

Una cuenta de Google con acceso a Google Sheets
Un archivo de credenciales de Service Account de Google Cloud Platform
Una hoja de cálculo de Google Sheets creada y compartida con la cuenta de servicio
El ID de la hoja de cálculo (extraído de la URL)

Cómo obtener el ID de la hoja de cálculo¶

El ID de la hoja de cálculo se encuentra en la URL de Google Sheets:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                                      ↑
                                              Este es el ID

Cómo crear una Service Account y obtener credenciales¶

Ve a Google Cloud Console
Crea un nuevo proyecto o selecciona uno existente
Habilita la Google Sheets API para tu proyecto
Ve a IAM & Admin → Service Accounts
Crea una nueva Service Account o usa una existente
Haz clic en la Service Account → Keys → Add Key → Create new key
Selecciona JSON como formato
Descarga el archivo JSON (este es el archivo de credenciales que necesitas)
Comparte tu hoja de cálculo con el email de la Service Account (aparece como client_email en el JSON)

Configuración del Nodo¶

La configuración del nodo se divide en tres secciones principales que puedes alternar usando el selector en la parte superior:

Sección 1: Configuración Básica¶

Paso 1: Configurar ID de la Hoja de Cálculo¶

En el campo "Spreadsheet ID", ingresa el ID de tu hoja de cálculo de Google Sheets
Ejemplo: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

Nota: Asegúrate de que la Service Account tenga acceso de lectura/escritura a esta hoja de cálculo.

Paso 2: Configurar Nombre de la Hoja¶

En el campo "Sheet Name", ingresa el nombre exacto de la hoja dentro de la hoja de cálculo
Ejemplo: Sheet1, Datos, Registros, etc.

Importante: El nombre debe coincidir exactamente con el nombre de la hoja, incluyendo mayúsculas y minúsculas.

Paso 3: Seleccionar Tipo de Acción¶

En el campo "Action Type", selecciona la operación que deseas realizar:

Acciones disponibles:

Add or Update Row (append_or_update): Agrega una nueva fila o actualiza una existente si ya hay una fila con el mismo valor en la columna de upsert
Add New Row (append): Agrega una nueva fila al final de la hoja
Update Row (update_row): Actualiza una fila específica por su índice
Get Rows (get_rows): Obtiene filas de un rango específico
Clear Range (clear): Limpia el contenido de un rango de celdas
Create New Sheet (create): Crea una nueva hoja dentro de la hoja de cálculo
Delete Sheet (delete): Elimina una hoja de la hoja de cálculo
Delete Rows/Columns (delete_rows_cols): Elimina filas o columnas específicas

Paso 4: Configurar Datos de Fila (Para acciones que escriben datos)¶

Si seleccionaste Add New Row, Add or Update Row, o Update Row:

En el campo "Row Data", ingresa los valores para cada columna
Cada campo representa una columna en orden (de izquierda a derecha)
Haz clic en "Add Field" para agregar más columnas
Haz clic en el icono de eliminar (🗑️) para quitar una columna

Ejemplo: - Campo 1: Juan Pérez - Campo 2: juan@ejemplo.com - Campo 3: 2024-01-15 - Campo 4: Activo

Esto creará una fila con estos valores en las columnas A, B, C y D respectivamente.

Nota: Puedes usar variables del contexto de automatización usando la sintaxis {{variable.nombre}}.

Sección 2: Configuración de Operación¶

Esta sección muestra campos adicionales según el tipo de acción seleccionada.

Para "Add or Update Row" y "Update Row"¶

Upsert Column: - Especifica la columna (letra, ej: A, B, C) que se usará para identificar si una fila ya existe - Para "Add or Update Row": Si existe una fila con el mismo valor en esta columna, se actualizará; si no, se agregará una nueva - Para "Update Row": Esta columna se usa junto con el índice de fila

Row Index: - El número de fila a actualizar (1 = primera fila de datos, sin contar encabezados) - Ejemplo: 1 actualiza la primera fila de datos, 2 la segunda, etc.

Para "Get Rows"¶

Start Row: - Número de la primera fila a leer (1 = primera fila de datos)

End Row: - Número de la última fila a leer

Start Column: - Letra de la columna inicial (ej: A, B, C)

End Column: - Letra de la columna final (ej: D, E, F)

Ejemplo: - Start Row: 1 - End Row: 10 - Start Column: A - End Column: D

Esto leerá las filas 1 a 10 y las columnas A a D.

Para "Delete Rows/Columns"¶

Delete Rows (JSON array): - Ingresa un array JSON con los números de fila a eliminar - Ejemplo: [5, 6, 7] elimina las filas 5, 6 y 7

Delete Columns (JSON array): - Ingresa un array JSON con las letras de columna a eliminar - Ejemplo: ["B", "C"] elimina las columnas B y C

Nota: Los números de fila y letras de columna deben estar en formato JSON válido.

Para "Clear Range"¶

Clear Range: - Especifica el rango de celdas a limpiar usando notación A1 - Ejemplos: - A1:D10 - Limpia desde A1 hasta D10 - B2:B100 - Limpia la columna B desde la fila 2 hasta la 100 - A1:Z1 - Limpia toda la primera fila

Para "Create New Sheet"¶

New Sheet Name: - El nombre que tendrá la nueva hoja creada - Ejemplo: Reporte Enero, Datos Importados, etc.

Sheet Properties (JSON): - Propiedades avanzadas de la hoja en formato JSON (opcional) - Ejemplo:

{
  "title": "Datos de Usuarios",
  "gridProperties": {
    "rowCount": 1000,
    "columnCount": 26
  }
}

Sección 3: Credenciales¶

Paso 5: Cargar Credenciales de Service Account¶

Haz clic en el botón "Upload Service Account JSON File"
Selecciona el archivo JSON de credenciales que descargaste de Google Cloud Console
El sistema validará el archivo y mostrará un mensaje de éxito si es válido
Verás información de confirmación mostrando el Project ID y Client Email

Importante: - El archivo debe ser un JSON válido con todos los campos requeridos - No compartas este archivo públicamente, contiene información sensible - Si necesitas eliminar las credenciales, haz clic en "Clear credentials"

Campos requeridos en el JSON: - type - project_id - private_key_id - private_key - client_email - client_id - auth_uri - token_uri - auth_provider_x509_cert_url - client_x509_cert_url - universe_domain

Ejemplos de Uso¶

Ejemplo 1: Registrar Evento en Hoja de Cálculo¶

Configuración Básica: - Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms - Sheet Name: Eventos - Action Type: Add New Row

Row Data: - Campo 1: {{context.event_name}} - Campo 2: {{context.timestamp}} - Campo 3: {{context.object_id}} - Campo 4: {{context.status}}

Uso: Cada vez que se dispara un evento, se registra automáticamente en la hoja de cálculo con la información del evento.

Ejemplo 2: Actualizar o Agregar Registro de Usuario¶

Configuración Básica: - Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms - Sheet Name: Usuarios - Action Type: Add or Update Row

Row Data: - Campo 1: {{context.user_email}} - Campo 2: {{context.user_name}} - Campo 3: {{context.last_login}} - Campo 4: {{context.status}}

Configuración de Operación: - Upsert Column: A (columna de email)

Uso: Si el email ya existe en la columna A, actualiza la fila; si no, agrega una nueva fila. Útil para mantener un registro actualizado de usuarios.

Ejemplo 3: Leer Datos de una Hoja¶

Configuración Básica: - Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms - Sheet Name: Configuracion - Action Type: Get Rows

Configuración de Operación: - Start Row: 1 - End Row: 50 - Start Column: A - End Column: C

Uso: Lee las primeras 50 filas y las columnas A a C. Los datos estarán disponibles en el contexto para usar en nodos posteriores.

Ejemplo 4: Limpiar Rango Antes de Escribir Nuevos Datos¶

Configuración Básica: - Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms - Sheet Name: Reporte Diario - Action Type: Clear Range

Configuración de Operación: - Clear Range: A2:Z1000

Uso: Limpia el rango especificado antes de escribir nuevos datos. Útil para reportes que se regeneran diariamente.

Ejemplo 5: Crear Nueva Hoja para Reporte Mensual¶

Configuración Básica: - Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms - Sheet Name: Sheet1 (cualquier nombre, se creará una nueva) - Action Type: Create New Sheet

Configuración de Operación: - New Sheet Name: Reporte Enero 2024 - Sheet Properties (JSON):

{
  "title": "Reporte Enero 2024",
  "gridProperties": {
    "rowCount": 5000,
    "columnCount": 26
  }
}

Uso: Crea automáticamente una nueva hoja cada mes para almacenar reportes.

Ejemplo 6: Eliminar Filas Antiguas¶

Configuración Básica: - Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms - Sheet Name: Logs - Action Type: Delete Rows/Columns

Configuración de Operación: - Delete Rows (JSON array): [1, 2, 3, 4, 5]

Uso: Elimina las primeras 5 filas de datos. Útil para mantener solo los registros más recientes.

Flujo de Trabajo en Automatizaciones¶

Estructura Típica¶

Trigger (por ejemplo, Trigger de Cambio de Estado) ↓
Acción Google Sheets (lee o escribe datos) ↓
Otras Acciones (usan los datos leídos o confirman la escritura)

Acceso a Resultados¶

Cuando usas la acción Get Rows, los datos leídos están disponibles en el contexto de la automatización y pueden ser utilizados por nodos posteriores. Los datos típicamente vienen en formato de array bidimensional.

Ejemplo de estructura de datos:

{
  "rows": [
    ["Valor1", "Valor2", "Valor3"],
    ["Valor4", "Valor5", "Valor6"]
  ]
}

Editor JSON (Avanzado)¶

Si tienes conocimientos técnicos, puedes editar la configuración directamente en formato JSON usando la pestaña "JSON Editor". La estructura es:

{
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "sheet_name": "Sheet1",
  "action": "append",
  "row_data": ["Valor1", "Valor2", "Valor3"],
  "data": [],
  "config": {
    "upsert_column": "A",
    "row_index": 1
  },
  "credentials": {
    "type": "service_account",
    "project_id": "tu-proyecto",
    "private_key_id": "...",
    "private_key": "...",
    "client_email": "...",
    "client_id": "...",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "...",
    "universe_domain": "googleapis.com"
  }
}

Solución de Problemas¶

Error de Autenticación¶

Problema: "Permission denied" o "The caller does not have permission"

Soluciones: 1. Verifica que hayas compartido la hoja de cálculo con el email de la Service Account (el client_email del archivo JSON) 2. Asegúrate de que la Service Account tenga permisos de "Editor" en la hoja de cálculo 3. Verifica que el archivo JSON de credenciales sea válido y esté completo 4. Comprueba que la Google Sheets API esté habilitada en tu proyecto de Google Cloud

Error: "Sheet not found"¶

Problema: No se encuentra la hoja especificada

Soluciones: 1. Verifica que el nombre de la hoja coincida exactamente (incluyendo mayúsculas/minúsculas y espacios) 2. Asegúrate de que la hoja exista en la hoja de cálculo 3. Si la hoja tiene caracteres especiales, verifica que estén escritos correctamente

Error: "Invalid spreadsheet ID"¶

Problema: El ID de la hoja de cálculo no es válido

Soluciones: 1. Verifica que hayas copiado el ID completo de la URL 2. Asegúrate de que no haya espacios adicionales antes o después del ID 3. Confirma que la hoja de cálculo existe y es accesible

Los Datos No Se Escriben Correctamente¶

Problema: Los datos aparecen en columnas incorrectas o faltan valores

Soluciones: 1. Verifica que el orden de los campos en "Row Data" corresponda al orden de las columnas 2. Asegúrate de que hayas agregado suficientes campos para todas las columnas que deseas llenar 3. Si usas variables, verifica que las variables existan y tengan valores en el contexto

Error al Leer Datos (Get Rows)¶

Problema: No se pueden leer los datos o el rango es inválido

Soluciones: 1. Verifica que las filas y columnas especificadas existan en la hoja 2. Asegúrate de que Start Row ≤ End Row y Start Column ≤ End Column (alfabéticamente) 3. Comprueba que el formato de las columnas sea correcto (letras: A, B, C, etc.)

Error al Eliminar Filas/Columnas¶

Problema: Error al procesar el array JSON de filas/columnas a eliminar

Soluciones: 1. Verifica que el formato JSON sea válido: [1, 2, 3] para filas, ["A", "B"] para columnas 2. Asegúrate de que los números de fila sean válidos (≥ 1) 3. Verifica que las letras de columna sean válidas (A-Z)

Mejores Prácticas¶

Seguridad¶

Nunca compartas tu archivo de credenciales públicamente o en repositorios de código
Usa Service Accounts dedicadas para automatizaciones en lugar de cuentas personales
Limita los permisos de la Service Account solo a las hojas de cálculo necesarias
Rota las credenciales periódicamente si es posible
No incluyas credenciales en el código o documentación

Organización de Datos¶

Usa la primera fila como encabezados para facilitar la lectura y mantenimiento
Mantén consistencia en el formato de datos (fechas, números, etc.)
Usa hojas separadas para diferentes tipos de datos o períodos de tiempo
Considera usar "Add or Update Row" con una columna única (como ID o email) para evitar duplicados

Rendimiento¶

Evita leer rangos muy grandes si no es necesario (usa filtros o límites)
Agrupa operaciones cuando sea posible en lugar de hacer múltiples llamadas pequeñas
Usa "Clear Range" antes de escribir grandes cantidades de datos nuevos
Considera el límite de escrituras de Google Sheets API (actualmente 300 solicitudes por minuto por proyecto)

Mantenimiento¶

Documenta la estructura de tus hojas de cálculo (qué columnas hay y qué significan)
Usa nombres descriptivos para las hojas y columnas
Versiona tus automatizaciones para poder revertir cambios si es necesario
Monitorea los errores y ajusta la configuración según sea necesario

Preguntas Frecuentes¶

P: ¿Puedo usar múltiples hojas de cálculo en una sola automatización? R: Sí, puedes usar múltiples nodos de Google Sheets, cada uno apuntando a diferentes hojas de cálculo.

P: ¿Qué pasa si la hoja no existe? R: La acción fallará con un error. Asegúrate de que la hoja exista antes de ejecutar la automatización, o usa la acción "Create New Sheet" primero.

P: ¿Puedo usar fórmulas de Google Sheets en los datos que escribo? R: Sí, puedes escribir fórmulas como valores de texto. Por ejemplo, puedes escribir =SUM(A1:A10) como un valor de celda.

P: ¿Hay límites en la cantidad de datos que puedo leer o escribir? R: Google Sheets API tiene límites de cuota. Consulta la documentación oficial de Google para los límites actuales. Generalmente, puedes leer/escribir hasta 10 millones de celdas por solicitud.

P: ¿Puedo leer datos de múltiples hojas en una sola acción? R: No, cada acción lee de una sola hoja. Si necesitas datos de múltiples hojas, usa múltiples nodos de Google Sheets.

P: ¿Qué formato tienen las fechas cuando las leo? R: Las fechas se leen como strings en el formato que tienen en la hoja de cálculo. Puedes convertirlas a formato de fecha en nodos posteriores si es necesario.

P: ¿Puedo usar esta acción para crear gráficos automáticamente? R: No directamente. Esta acción maneja datos, pero los gráficos deben crearse manualmente en Google Sheets o usando la API de Google Sheets de forma más avanzada.

P: ¿Qué pasa si intento escribir en una celda que tiene una fórmula? R: La fórmula será reemplazada por el valor que escribas. Ten cuidado al escribir datos en rangos que contienen fórmulas.

P: ¿Puedo usar variables del contexto en los nombres de hojas o IDs? R: Sí, puedes usar variables usando la sintaxis {{variable.nombre}} en los campos de texto, incluyendo Spreadsheet ID y Sheet Name.