Excel Online Activities

Versión: 1.0.4 · ID: zoan-packages-excelonline · Autor: Zoan Software

El paquete Excel Online lee y escribe libros .xlsx alojados en OneDrive o SharePoint a través de Microsoft Graph. Ofrece las mismas operaciones que el paquete Excel local (hoja, rango, celda), pero sobre la nube y con autoguardado: cada escritura queda guardada en el libro en el momento, sin paso de Save, y la ven al instante las personas que lo tienen abierto. No necesita Excel instalado en la máquina del robot.

Concepto 1: autenticación y permisos

Las actividades se autentican con una conexión OAuth de Microsoft 365 de Zoan Cloud. En Connect la referencias con la función credential() y su nombre clave:

Excel Online — Connect   credential = credential("m365-finanzas")   path = "Reportes/Ventas.xlsx"

Zoan Cloud entrega a la actividad un token de acceso vigente (lo renueva solo). Al crear la conexión, marca los permisos (scopes) de Microsoft Graph que cubran los libros que vas a abrir:

Permiso de Microsoft Graph	Para qué
`Files.ReadWrite`	Leer y escribir libros del OneDrive de la cuenta que autorizó la conexión.
`Files.ReadWrite.All`	Libros de otros usuarios (`mailbox`) o compartidos con la cuenta.
`Sites.ReadWrite.All`	Libros guardados en bibliotecas de documentos de SharePoint (`driveId`).
`offline_access`	Que Zoan Cloud pueda renovar el token sin volver a pedir el consentimiento.

Si solo vas a leer, bastan los permisos .Read equivalentes (Files.Read, Files.Read.All, Sites.Read.All); con ellos las escrituras fallan con accessDenied.

Concepto 2: cómo se identifica el libro

Connect ubica el libro con dos datos:

Dato	Qué es	Cómo se obtiene
Unidad (`driveId`)	El OneDrive o la biblioteca de documentos donde está el libro.	Por defecto, el OneDrive de la cuenta de la conexión (o el de `mailbox`). Para SharePoint, el ID de la biblioteca (Microsoft Graph lo devuelve en `/sites/{sitio}/drives`).
Libro (`path` o `itemId`)	El archivo dentro de esa unidad.	`path` es la ruta desde la raíz de la unidad (`Reportes/Ventas.xlsx`); `itemId` es el ID del archivo, por ejemplo el `id` que devuelve OneDrive/SharePoint — List files.

Dentro del libro, las hojas se indican por nombre (sheet) y las celdas y rangos en notación A1 (B3, A1:D20). El libro debe ser .xlsx.

Concepto 3: la sesión

Todas las operaciones trabajan sobre la sesión que abre Connect:

Con body: las actividades que pones dentro heredan la sesión y esta se cierra sola al terminar el bloque.
Sin body: Connect devuelve la sesión; pásala por session a las demás actividades y ciérrala con Close.

Concepto 4: formas de salida

Actividad	Devuelve
Read sheet	`DataTable` con el rango usado de la hoja.
Read range	`DataTable` si `has-headers = true`; si no, una `List` de filas (cada fila es una `List` de valores).
Read cell	El valor de la celda (`string`, número o `bool`).
Used range	`Dictionary` con `rows`, `columns` y `address`.
Find cell	`Dictionary` con `address`, `row`, `column` y `value`, o `null` si no hay coincidencia.
Get sheet names	`List<string>` con los nombres de las hojas, en su orden.

Los valores llegan tal como los guarda Excel: los números como número, los textos como string, las celdas vacías como texto vacío ("") y las fechas como número de serie de Excel (por ejemplo 45458); conviértelas con DateTime.FromOADate(...) si necesitas una fecha. Las escrituras (Write sheet, Write range, Append rows) reciben una DataTable (o una sola DataRow) y escriben solo los valores de las filas, sin la fila de nombres de columna.

Concepto 5: errores de la API

Además de las validaciones propias de cada actividad, Microsoft Graph puede rechazar una operación. El error llega con el mensaje y el código que devuelve Microsoft (en inglés):

Código de Microsoft Graph	Causa habitual	Qué hacer
`InvalidAuthenticationToken` (401)	El valor de `credential` no es un token válido (por ejemplo, se escribió el nombre de la conexión sin `credential()`), o el token venció.	Usa `credential("nombre-clave")` y verifica que la conexión esté Conectada en Zoan Cloud.
`accessDenied` (403)	A la conexión le falta un permiso, o la cuenta no tiene acceso al libro.	Agrega el permiso a la conexión y reconéctala, o comparte el libro con la cuenta.
`itemNotFound` (404)	El libro, la unidad o la hoja no existen con ese nombre, ruta o ID.	Revisa `path`/`itemId`/`driveId` y el nombre de la hoja (con Get sheet names).
`InvalidArgument` (400)	Dirección A1 no válida, o un rango cuyo tamaño no coincide con los datos.	Revisa `cell`/`range`; usa Write sheet para que el rango se calcule solo.
429, 503 o 504	Microsoft limita temporalmente las solicitudes o el servicio no responde.	Envuelve la actividad en un Retry con espera entre intentos.

Para que el proceso siga ante un fallo, usa Try / Catch.

Actividades

Actividad	Tipo	Salida	Descripción
Excel Online — Connect	`excelonline-connect`	`ZoanExcelOnlineSession`	Abre un libro de Excel Online (Microsoft Graph) por ruta o ID de elemento
Excel Online — Read sheet	`excelonline-read-sheet`	`DataTable`	Lee todos los datos de una hoja y los devuelve como DataTable
Excel Online — Read range	`excelonline-read-range`	`DataTable \| List`	Lee un rango de celdas
Excel Online — Read cell	`excelonline-read-cell`	`object`	Lee el valor de una sola celda
Excel Online — Write sheet	`excelonline-write-sheet`	—	Escribe un conjunto de datos en la hoja empezando en A1
Excel Online — Write range	`excelonline-write-range`	—	Escribe valores en un rango (debe coincidir con el tamaño de los datos)
Excel Online — Write cell	`excelonline-write-cell`	—	Escribe un valor en una sola celda
Excel Online — Append rows	`excelonline-append-rows`	—	Agrega filas después de los últimos datos existentes en una hoja
Excel Online — Clear range	`excelonline-clear-range`	—	Borra el contenido de un rango de celdas
Excel Online — Used range	`excelonline-get-used-range`	`Dictionary<string,object>`	Devuelve las dimensiones del área usada: filas, columnas y dirección
Excel Online — Get sheet names	`excelonline-get-sheet-names`	`List<string>`	Devuelve la lista de nombres de hoja del libro
Excel Online — Find cell	`excelonline-find-cell`	`Dictionary<string,object>`	Busca la primera celda con un valor dado
Excel Online — Close	`excelonline-close`	—	Cierra una sesión de Excel Online