OneDrive & SharePoint Activities

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

El paquete OneDrive / SharePoint gestiona archivos (subir, descargar, buscar, mover, compartir) y, además, los elementos de listas de SharePoint (leer, añadir, actualizar, borrar) a través de Microsoft Graph. Trabaja directamente sobre la nube de Microsoft 365, sin cliente de sincronización ni unidades mapeadas 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:

OneDrive/SharePoint — Connect   credential = credential("m365-operaciones")

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 necesitan tus actividades:

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

Si el proceso solo lee, bastan los permisos .Read equivalentes (Files.Read, Files.Read.All, Sites.Read.All). La conexión actúa como la cuenta que la autorizó: solo ve y modifica lo que esa cuenta puede ver y modificar en Microsoft 365.

Concepto 2: cómo se identifican unidades, archivos, sitios y listas

Qué	Cómo se indica	De dónde sale
Unidad (OneDrive o biblioteca)	`driveId` en Connect. Sin él, el OneDrive de la cuenta de la conexión (o el de `mailbox`).	Para una biblioteca de SharePoint, Microsoft Graph devuelve su ID en `/sites/{siteId}/drives`.
Archivo o carpeta	Por ID (`id`, `folderId`) en casi todas las actividades.	La clave `id` que devuelven List files, Upload, Create folder, Get info y Move.
Ruta	Solo en Upload (`destination`): ruta desde la raíz de la unidad, `Informes/2026/resumen.pdf`.	La escribes tú.
Sitio de SharePoint	`siteId` en Connect. Solo lo necesitan las actividades de listas.	Microsoft Graph lo devuelve en `/sites/{servidor}:/sites/{nombre}`; tiene la forma `contoso.sharepoint.com,<guid>,<guid>`.
Lista	`list`: nombre visible o ID de la lista.	El nombre que ves en SharePoint, o el ID de la lista.
Elemento de lista	`itemId`.	La clave `id` que devuelven Get list items y Add list item.

driveId y siteId son independientes: con siteId las listas apuntan al sitio, pero los archivos siguen en la unidad de driveId (o en el OneDrive si no lo indicas). Para trabajar con los archivos de un sitio, pasa también el driveId de su biblioteca.

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

Las actividades de archivos devuelven los metadatos de cada elemento como un Dictionary<string,object> con estas claves:

Clave	Tipo	Contenido
`id`	`string`	ID del archivo o carpeta. Es lo que piden las demás actividades.
`name`	`string`	Nombre con extensión.
`isFolder`	`bool`	`true` si es una carpeta.
`size`	número	Tamaño en bytes (en carpetas, el total de su contenido).
`webUrl`	`string`	Dirección para abrirlo en el navegador (requiere acceso).
`parentId`	`string`	ID de la carpeta que lo contiene.
`modifiedTime`	`string`	Fecha de última modificación, ISO 8601 en UTC (`2026-10-15T14:03:22.0000000+00:00`).
`createdTime`	`string`	Fecha de creación, mismo formato.
`childCount`	número	Cantidad de elementos dentro (solo carpetas; `null` en archivos).

List files devuelve una lista de estos diccionarios; Get list items devuelve una lista de { id, fields }, donde fields es un diccionario con las columnas de la lista por su nombre interno.

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, la cuenta no tiene acceso al elemento, o una política de la organización lo impide (por ejemplo, enlaces anónimos deshabilitados).	Agrega el permiso a la conexión y reconéctala, o pide acceso al elemento.
`itemNotFound` (404)	El ID, la ruta, la unidad, el sitio o la lista no existen (o están en otra unidad que la de la sesión).	Revisa el ID y el `driveId`/`siteId` de Connect.
`nameAlreadyExists` (409)	Ya hay un elemento con ese nombre en la carpeta de destino.	Usa otro nombre o elimina antes el existente.
`invalidRequest` (400)	Un valor no válido: nombre con caracteres no permitidos, columna de lista inexistente, formato de conversión no soportado.	Revisa los valores enviados.
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

Archivos (OneDrive / SharePoint)

Actividad	Tipo	Salida	Descripción
OneDrive/SharePoint — Connect	`msfiles-connect`	`ZoanMicrosoftFilesSession`	Abre una sesión de OneDrive / SharePoint vía Microsoft Graph
OneDrive/SharePoint — Upload	`msfiles-upload`	`Dictionary<string,object>`	Sube un archivo local a una ruta de la unidad (hasta 250 MB)
OneDrive/SharePoint — Download	`msfiles-download`	`string`	Descarga un archivo a una ruta local; puede exportar documentos de Office a PDF
OneDrive/SharePoint — List files	`msfiles-list`	`List<Dictionary<string,object>>`	Lista el contenido de una carpeta o busca por texto
OneDrive/SharePoint — Get info	`msfiles-get-info`	`Dictionary<string,object>`	Obtiene los metadatos de un archivo o carpeta por su ID
OneDrive/SharePoint — Create folder	`msfiles-create-folder`	`Dictionary<string,object>`	Crea una carpeta
OneDrive/SharePoint — Copy	`msfiles-copy`	—	Copia un archivo o carpeta
OneDrive/SharePoint — Move	`msfiles-move`	`Dictionary<string,object>`	Mueve (y opcionalmente renombra) un archivo o carpeta
OneDrive/SharePoint — Share	`msfiles-share`	`Dictionary<string,object>`	Comparte un archivo o carpeta: crea un enlace o invita por email
OneDrive/SharePoint — Delete	`msfiles-delete`	—	Elimina un archivo o carpeta (lo mueve a la papelera de reciclaje)
OneDrive/SharePoint — Close	`msfiles-close`	—	Cierra una sesión de OneDrive/SharePoint

Listas de SharePoint

Actividad	Tipo	Salida	Descripción
SharePoint — Get list items	`msfiles-get-list-items`	`List<Dictionary<string,object>>`	Lee los elementos de una lista de SharePoint (con sus campos)
SharePoint — Add list item	`msfiles-add-list-item`	`string`	Añade un elemento a una lista de SharePoint
SharePoint — Update list item	`msfiles-update-list-item`	—	Actualiza los campos de un elemento de una lista de SharePoint
SharePoint — Delete list item	`msfiles-delete-list-item`	—	Elimina un elemento de una lista de SharePoint