Google Sheets Activities

Versión: 1.0.5  ·  ID: zoan-packages-googlesheets  ·  Autor: Zoan Software

El paquete Google Sheets lee y escribe hojas de cálculo de Google directamente en la nube (a través de su API). Es el equivalente de Excel para documentos de Google: ideal cuando los datos viven en una hoja compartida que varias personas o sistemas actualizan, sin descargar ni volver a subir archivos.

Concepto 1: la autenticación

A diferencia de Excel (que abre un archivo local), Google Sheets accede a una hoja en la nube, así que necesita autorización. Google Sheets — Open admite dos modos, que eliges con authType:

Modo	Qué necesitas	Cuándo conviene
oauth (por defecto)	Una conexión OAuth de Google creada y autorizada en Zoan Cloud con el permiso de Sheets. Se pasa en credential como credential("nombre-clave"). Zoan Cloud renueva el token solo.	El robot actúa sobre la cuenta de una persona o de un buzón del equipo.
service-account	Una llave de service account (el JSON completo) guardada como credencial, en serviceAccount. La hoja debe estar compartida con el email de la service account. Opcional: impersonateUser para actuar en nombre de un usuario del Workspace (domain-wide delegation).	Ejecuciones desatendidas sin consentimiento de una persona.

En los dos modos las actividades usan el permiso de lectura y escritura de hojas de cálculo (https://www.googleapis.com/auth/spreadsheets).

Lo que necesitas	Dónde se obtiene
ID de la hoja (spreadsheetId)	Está en la URL de la hoja: docs.google.com/spreadsheets/d/{ID}/edit — copia la parte {ID}.

Concepto 2: la sesión

Todas las operaciones trabajan sobre una sesión (ZoanGoogleSheetsSession) que abres con Google Sheets — Open y compartes con las demás actividades:

• Con body: las actividades dentro heredan la sesión sin indicar session; al terminar se cierra sola, aunque algo falle.
• Sin body: guardas la sesión en una variable, la pasas en session y la cierras con Google Sheets — Close.

Google Sheets — Open   credential = credential("google-operaciones")   spreadsheetId = idHoja
 └─ body:
      Google Sheets — Read sheet   sheet = "Pedidos"   has-headers = true   → output: pedidos
      ... procesar ...

Abrir no comprueba el acceso

Open solo prepara la sesión: no llama a Google. Si el ID de la hoja es incorrecto o la cuenta no tiene acceso, el error aparece en la primera lectura o escritura.

Notación A1, hojas y valores

• Celdas y rangos usan notación A1: A1, B3, A1:E10, A:E (columnas completas), 1:100 (filas completas).
• Hojas: por nombre ("Pedidos"). Si lo omites, se usa la primera hoja del documento. Escribe el nombre tal cual, sin comillas: la actividad lo pone entre comillas simples y duplica el apóstrofo que tenga, así funcionan nombres como Ventas O'Brien, Hoja con espacios o A1. Desde la versión 1.0.5.
• Lo que se lee es texto: las lecturas devuelven el valor tal como se ve en la hoja (con su formato de número y fecha), siempre como string. Convierte con num() o con las funciones de fecha antes de calcular. Una fórmula se lee como su resultado.
• has-headers: en Read sheet y Read range, con true la primera fila da los nombres de columna de la DataTable; con false (por defecto) las columnas se llaman Column1, Column2, … El resultado es siempre una DataTable.

Las escrituras admiten fórmulas

Al escribir, los valores se interpretan como USER_ENTERED: si escribes =SUM(A1:A10), Google Sheets lo guarda como fórmula, igual que si lo teclearas tú; 2026-06-15 queda como fecha y 1500 como número.

Actividades

Sesión

Actividad	Tipo	Salida	Qué hace
Google Sheets — Open	googlesheets-open	ZoanGoogleSheetsSession	Abre una sesión autenticada con una hoja
Google Sheets — Close	googlesheets-close	—	Cierra la sesión

Leer

Actividad	Tipo	Salida	Qué hace
Read sheet	googlesheets-read-sheet	DataTable	Lee toda una hoja
Read range	googlesheets-read-range	DataTable	Lee un rango
Read cell	googlesheets-read-cell	object	Lee una celda
Used range	googlesheets-get-used-range	Dictionary<string,object>	Dimensiones del área con datos
Get sheet names	googlesheets-get-sheet-names	List<string>	Nombres de las hojas
Find cell	googlesheets-find-cell	Dictionary<string,object>	Encuentra una celda por valor
Find row	googlesheets-find-row	Dictionary<string,object>	Encuentra una fila por valor de columna

Escribir

Actividad	Tipo	Salida	Qué hace
Write sheet	googlesheets-write-sheet	—	Escribe datos desde A1
Write range	googlesheets-write-range	—	Escribe desde una celda
Write cell	googlesheets-write-cell	—	Escribe una celda
Append rows	googlesheets-append	—	Agrega filas al final
Clear range	googlesheets-clear-range	—	Limpia el contenido de un rango

Errores de la API de Google

Cuando Google rechaza una llamada, la actividad falla con un error de tipo GoogleApiException cuyo mensaje empieza por The service sheets has thrown an exception. HttpStatusCode is … seguido del texto de Google (siempre en inglés: lo envía Google). El código indica la causa:

Código	Causa habitual	Qué hacer
NotFound	El spreadsheetId no existe o se copió mal.	Copia el ID desde la URL de la hoja.
BadRequest (Unable to parse range: …)	La hoja o el rango no existen (nombre de hoja mal escrito, rango inválido).	Comprueba los nombres con Get sheet names.
Forbidden	La cuenta no tiene acceso a la hoja, o la conexión no incluye el permiso de Sheets.	Comparte la hoja con la cuenta (o con el email de la service account) o reautoriza la conexión con el permiso.
Unauthorized	El token ya no es válido (acceso revocado, conexión expirada).	Reconectar la conexión en Zoan Cloud.
TooManyRequests	Se superó la cuota de solicitudes por minuto de Google.	Agrupa lecturas y escrituras (una DataTable en vez de muchas celdas) y envuelve la actividad en Retry con espera.

Captura cualquiera de ellos con Try / Catch; error.Type vale GoogleApiException.

Siguientes pasos

• Google Sheets — Open — abrir una hoja.
• Read sheet — leer datos a una DataTable.
• Excel — el equivalente para archivos .xlsx locales.