Google Sheet Cells

El componente Google Sheet Cells te permite leer, crear, actualizar y eliminar filas en una hoja de cálculo de Google Sheets directamente desde el panel de Nappai. Con él puedes automatizar tareas que requieran manipular datos en Google Sheets sin salir de tu flujo de trabajo.

¿Cómo funciona?

Cuando lo añades a tu flujo, el componente se conecta a la API de Google Sheets usando la credencial que hayas configurado previamente. Dependiendo de la operación seleccionada, envía una solicitud a la API para:

Add Row: Inserta una nueva fila con los valores que indiques.
Update Row: Modifica una fila existente identificada por su número.
Delete Row: Elimina una fila específica (excepto la primera, que suele ser la cabecera).
Get Rows: Recupera filas dentro de un rango o toda la hoja.

El componente también admite un Modo de Mapeo que permite procesar varios registros a la vez, lo que es útil cuando quieres aplicar la misma operación a una lista de datos.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

Add Row: Inserta una nueva fila con los valores proporcionados.
Update Row: Actualiza una fila existente con nuevos valores.
Delete Row: Elimina una fila específica (no puede ser la primera).
Get Rows: Recupera filas de la hoja según el rango indicado.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

Fixed (Fijo): Escribes el valor directamente en el campo.
Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

Select Spreadsheet: Selecciona el archivo de Google Spreadsheet. Si se proporciona un Spreadsheet Id, este campo se ignora.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Values: Valores a usar. Se requiere un dato donde cada columna sea una clave y el valor sea el texto a añadir a la fila.
- Visible en: Add Row, Update Row
Operation: Selecciona la operación que deseas ejecutar.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Column Recognition: Reconoce automáticamente los nombres de columna desde la hoja o permite que el usuario los defina mediante un dato.
- Visible en: Add Row, Update Row
First row: Indica si la primera fila contiene encabezados.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Hoja actual: Nombre de la hoja actual que se usará.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Declare Headers: Declara que el primer elemento de una columna es un encabezado de la tabla.
- Visible en: Get Rows
Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Mode of Input: Modo de entrada a usar.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Range: Rango a usar. Si se deja vacío, se usará toda la hoja por defecto. Añadir un valor lo colocará en la siguiente celda disponible después de la última entrada existente.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Row Number: Número de fila que determina la fila a actualizar o eliminar. En operaciones de eliminación no puede ser 1 porque no se pueden eliminar encabezados.
- Visible en: Update Row, Delete Row
Select Sheet: Selecciona la hoja del spreadsheet que se usará.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Spreadsheet ID: ID del Spreadsheet a usar. Si se selecciona un archivo, este campo se ignora.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Tool Name: Nombre del tool que se usará cuando el componente esté conectado como herramienta. Este nombre se mostrará al agente cuando elija herramientas.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Tool Description: Descripción detallada de lo que hace esta herramienta. Ayuda al agente a entender cuándo y cómo usarla.
- Visible en: Add Row, Update Row, Delete Row, Get Rows
Tools arguments metadata: Define los metadatos de los argumentos para las herramientas.
- Visible en: Add Row, Update Row, Delete Row, Get Rows

Nota: Este componente necesita una credencial de tipo Google Sheets API. Configura la credencial en la sección de credenciales de Nappai y luego selecciónala en el campo “Credential” del componente.

Salidas

Data: Devuelve los datos obtenidos o confirmación de la operación en formato Data (método: perfom_operation).
Json: Devuelve los datos en formato JSON como texto (método: values_to_json).
Tool: Devuelve la herramienta configurada para que pueda ser usada por un agente (método: to_toolkit).

Ejemplo de Uso

Añadir una fila

Arrastra el componente Google Sheet Cells a tu flujo.
Selecciona la operación Add Row.
En Select Spreadsheet elige el archivo de Google Sheets o ingresa el Spreadsheet ID.

En Values escribe los datos en formato JSON, por ejemplo:

{
  "Nombre": "Juan Pérez",
  "Edad": "30",
  "Departamento": "Ventas"
}

Configura Select Sheet con el nombre de la hoja donde quieres insertar la fila.
Haz clic en Run.
El componente añadirá la fila y devolverá la confirmación en la salida Data.

Obtener filas

Selecciona la operación Get Rows.
En Range escribe el rango que quieres leer, por ejemplo A1:C10.
En Select Sheet elige la hoja.
Ejecuta el flujo.
El componente devolverá las filas en la salida Data y también en formato JSON en Json.

Componentes Relacionados

GoogleRowsSheet – Base que maneja operaciones básicas con filas de Google Sheets.
GoogleSheetsIcon – Icono visual que representa la integración con Google Sheets.

Consejos y Mejores Prácticas

Usa el Modo de Mapeo cuando necesites procesar listas de datos; evita ejecutar el componente varias veces.
Define encabezados con la opción Declare Headers para que la API reconozca correctamente las columnas.
Limita el rango cuando solo necesites leer o actualizar una sección específica; esto reduce la latencia.
Revisa los permisos de la credencial; solo otorga acceso de lectura/escritura a los spreadsheets que realmente necesites.

Consideraciones de Seguridad

La credencial de Google Sheets API contiene datos sensibles (Client Id y Client Secret). Guárdala en un lugar seguro y no la compartas.
Asegúrate de que la cuenta de Google asociada tenga los permisos mínimos necesarios para la tarea.
Si compartes flujos con otros usuarios, revisa que no incluyan credenciales expuestas en los campos de entrada.