Documentación: Nodo Microsoft Excel¶
Descripción General¶
El Nodo Microsoft Excel es un nodo de acción de integración que permite leer y escribir datos en archivos de Microsoft Excel alojados en OneDrive / SharePoint, a través de la API de Microsoft Graph. Soporta operaciones de lectura, actualización, limpieza y adición de filas sobre una hoja de cálculo.
En entornos IoT, es ideal para registrar datos operativos en hojas de Excel corporativas (bitácoras de eventos, lecturas de sensores, reportes de asistencia) de forma automática, integrando la plataforma con el ecosistema Microsoft 365.
¿Cuándo usar este nodo?¶
Utiliza este nodo cuando necesites:
- Registrar eventos o lecturas en una hoja de Excel (por ejemplo, agregar una fila cada vez que se dispara una alarma).
- Leer datos de una hoja para usarlos en la lógica del flujo (umbrales, listas de configuración).
- Actualizar o limpiar rangos de una hoja de cálculo automáticamente.
- Integrar la plataforma con reportes y bitácoras gestionados en Microsoft 365 / OneDrive / SharePoint.
Configuración del Nodo¶
El nodo cuenta con dos pestañas de configuración en la parte superior: Formulario (Form) y Editor de JSON (JSON Editor). El formulario se organiza en dos secciones seleccionables: Basic Configuration y Action Data.
Sección: Basic Configuration (Configuración Básica)¶
1. Credenciales (Credentials) *Requerido¶
Selecciona la credencial de Microsoft Graph (que contiene client_id, client_secret y tenant_id) para autenticar el acceso a los archivos. Se gestiona de forma centralizada y segura.
2. Drive ID *Requerido¶
El identificador del drive (OneDrive/SharePoint) donde se encuentra el archivo (por ejemplo, b!abc123...).
3. Item ID *Requerido¶
El identificador del archivo de Excel dentro del drive (por ejemplo, 01ABCDEF...).
4. Nombre de la Hoja (Worksheet Name) *Requerido¶
El nombre de la hoja de cálculo sobre la que se opera (por ejemplo, Registros).
5. Acción (Action) *Requerido¶
La operación a realizar. Opciones:
| Acción | Valor | Descripción |
|---|---|---|
| Get Range | get_range |
Lee el contenido de un rango de celdas. |
| Update Range | update_range |
Escribe/actualiza un rango con una matriz de datos. |
| Clear Range | clear_range |
Limpia el contenido de un rango. |
| Append Row | append_row |
Agrega una nueva fila al final de la tabla. |
6. Dirección del Rango (Range Address)¶
El rango de celdas sobre el que se opera (por ejemplo, A1:D10). Requerido para get_range, update_range y clear_range.
Sección: Action Data (Datos de la Acción)¶
El contenido de esta sección depende de la acción seleccionada:
- Append Row: muestra una lista Row Data donde agregas los valores de la nueva fila (uno por columna) con el botón
Add Value. Cada valor admite expresiones de plantilla. - Update Range: muestra un campo Data (JSON matrix) para ingresar una matriz de filas (por ejemplo,
[["Name","Age"],["Ana","30"]]). - Get Range / Clear Range: no requieren datos adicionales.
Vista Editor de JSON¶
En la pestaña Editor de JSON (JSON Editor) puedes visualizar y editar directamente toda la configuración:
Estructura JSON (Parámetros de entrada)¶
A continuación se muestra la estructura del JSON que se genera al configurar el nodo (acción append_row):
{
"drive_id": "b!aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
"item_id": "01ABCDEF1234567890",
"worksheet_name": "Records",
"action": "append_row",
"range_address": "A1:D1",
"row_data": [
"{{trigger.datetime}}",
"{{trigger.object_name}}",
"{{trigger.state.state}}"
],
"data": []
}
Campos del JSON¶
| Campo | Tipo | Descripción |
|---|---|---|
drive_id |
string | ID del drive (OneDrive/SharePoint). |
item_id |
string | ID del archivo de Excel. |
worksheet_name |
string | Nombre de la hoja de cálculo. |
action |
string | Operación: get_range, update_range, clear_range, append_row. |
range_address |
string | Rango de celdas (ej. A1:D10). Requerido para get/update/clear. |
row_data |
array (string) | Valores de la fila a agregar (para append_row). |
data |
array (array) | Matriz de filas para update_range (ej. [["Name","Age"],["Ana","30"]]). |
credentials |
object | Referencias a la credencial de Microsoft Graph (gestionada de forma segura). |
Output: Dónde viene la data del nodo¶
- Para acciones de lectura (
get_range), el nodo devuelve en su Output (Salida) el contenido del rango leído, que puede usarse en nodos posteriores con{{node_key}}. - Para acciones de escritura (
update_range,clear_range,append_row), el nodo confirma la operación al ejecutarse correctamente (borde verde).
Ejemplos de uso¶
Ejemplo 1: Registrar cada alarma en una bitácora de Excel¶
Caso de uso: Cada vez que se dispara una alarma, se agrega una fila a una hoja de Excel con la fecha, el dispositivo y el estado.
- Action:
Append Row - Row Data:
{{trigger.datetime}},{{trigger.object_name}},{{trigger.state.state}}
JSON de configuración: (ver estructura anterior)
Ejemplo 2: Leer una lista de umbrales desde Excel¶
Caso de uso: Leer un rango con los umbrales de temperatura configurados por planta para usarlos en la lógica del flujo.
- Action:
Get Range - Range Address:
A1:B20
Validación y errores¶
| Condición | Causa / Solución habitual |
|---|---|
| Error de autenticación | La credencial de Microsoft Graph es incorrecta o carece de permisos sobre el archivo. |
| Archivo no encontrado | Verifica drive_id e item_id; deben corresponder a un archivo de Excel accesible. |
| Rango inválido | Revisa el formato de range_address (ej. A1:D10) y que la hoja (worksheet_name) exista. |
Buenas prácticas¶
- Usar credenciales centralizadas: No escribas client_id/secret en el nodo; selecciona una credencial de Microsoft Graph gestionada de forma segura.
- Append Row para bitácoras: Para registros incrementales (logs),
append_rowes la opción más simple y segura. - Plantillas en los valores: Aprovecha las expresiones de plantilla en
row_datapara registrar datos dinámicos del evento. - Nombrar el nodo descriptivamente: Cambia el nombre del nodo en el lienzo (ej. "Registrar alarma en Excel") para identificarlo en el flujo.