Saltar a contenido

Proveedor de Almacenamiento Microsoft SharePoint

El proveedor de almacenamiento Microsoft SharePoint es una funcionalidad opcional de Clarive con licencia separada que permite almacenar adjuntos de tópicos y activos binarios directamente en Microsoft SharePoint Online. Utiliza la API de Microsoft Graph para gestionar archivos en la biblioteca de documentos de un sitio SharePoint.

Nota: Esta es una funcionalidad de pago adicional. El módulo mssharepoint debe estar instalado para que el tipo de recurso MSSharePointSite esté disponible.

Requisitos Previos

Antes de configurar el proveedor SharePoint, necesita:

  • Un inquilino (tenant) de Microsoft 365 con SharePoint Online
  • Un Registro de Aplicación en Azure AD (Entra ID) con los permisos requeridos
  • El Site ID de SharePoint (y opcionalmente un Drive ID)
  • El módulo mssharepoint instalado en su instancia de Clarive

Registro de Aplicación en Azure AD

Registre una aplicación en Azure AD para permitir que Clarive acceda a SharePoint:

  1. Vaya a Portal Azure → Azure Active Directory → Registros de aplicaciones
  2. Haga clic en Nuevo registro y proporcione un nombre (ej., "Clarive SharePoint Integration")
  3. En Certificados y secretos, cree un nuevo Secreto de cliente y copie el valor inmediatamente
  4. En Permisos de API, agregue los siguientes Permisos de aplicación para Microsoft Graph:
  5. Sites.ReadWrite.All
  6. Files.ReadWrite.All
  7. Haga clic en Conceder consentimiento de administrador para los permisos
  8. Anote los siguientes valores:
  9. Tenant ID (desde la página de Información general)
  10. ID de aplicación (cliente) (desde la página de Información general)
  11. Valor del secreto de cliente (del paso 3)

Obtener el Site ID y Drive ID

Utilice la API de Microsoft Graph para obtener los identificadores de SharePoint.

Site ID

curl -H "Authorization: Bearer <access_token>" \
  "https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/<nombre-sitio>"

La respuesta incluye un campo id — este es su Site ID.

Drive ID

curl -H "Authorization: Bearer <access_token>" \
  "https://graph.microsoft.com/v1.0/sites/<site-id>/drives"

Cada entrada en el array value tiene un campo id. Use el que corresponda a la biblioteca de documentos que desea. Si solo tiene una biblioteca, puede dejar el Drive ID configurado como root.

Crear el Recurso SharePoint

  1. Navegue a Recursos en la interfaz de Clarive
  2. Haga clic en Nuevo para crear un nuevo recurso
  3. Seleccione MSSharePointSite de la lista de tipos de recurso
  4. Complete los campos de configuración:
Campo Requerido Descripción
Activo No Habilitar o deshabilitar el proveedor. Habilitado por defecto.
Tenant ID Sí El identificador de inquilino de Microsoft 365 / Azure AD.
Client ID Sí El ID de aplicación (cliente) del Registro de Aplicación en Azure AD.
Client Secret Sí El valor del secreto de cliente del Registro de Aplicación. Se almacena cifrado.
Site ID Sí El identificador del sitio SharePoint obtenido de la API Graph.
Drive ID No El ID de unidad de la biblioteca de documentos. Por defecto root (la biblioteca predeterminada).
Root Path No Una ruta de carpeta base. Todas las operaciones se limitarán a esta ruta.
  1. Haga clic en Guardar

Asignar el Proveedor a Campos

Una vez creado el recurso SharePoint, asígnelo a campos de adjuntos de tópicos:

  1. Abra el editor de Categoría para el tipo de tópico que desea configurar
  2. En la configuración del campo Adjuntar Archivos, establezca:
  3. Storage Provider — seleccione su recurso de Sitio SharePoint
  4. Storage Folder — la ruta de la carpeta en SharePoint donde se almacenarán los archivos (ej., /FromClarive)

Los archivos cargados a través de ese campo se almacenarán en la ubicación configurada de SharePoint en lugar del GridFS predeterminado.

Sustitución de Variables en la Carpeta de Almacenamiento

La ruta de Storage Folder soporta sustitución dinámica de variables usando la sintaxis ${variable}. Las variables se resuelven a partir de los datos del tópico en el momento de la carga.

Ejemplos

/Documentos/${title}
/Proyectos/${category}
/Ambientes/${environment}/Proyectos/${project}

Reglas de Resolución de Variables

  • Los campos del tópico están disponibles directamente: ${title}, ${status}, ${category}
  • Los campos que referencian otros Recursos (CIs) se resuelven automáticamente al nombre del recurso
  • Los campos de tipo array con un solo valor se tratan como escalares
  • Para campos de tipo array con múltiples valores, se usa el primer valor

Ejemplo

Dado un tópico con: - Título: "Release v2.0" - Proyecto: "MiProyecto" (una referencia a CI) - Ambiente: "Producción" (una referencia a CI)

Y una carpeta de almacenamiento configurada como: /Proyectos/${project}/${environment}

La ruta resuelta será: /Proyectos/MiProyecto/Producción

Cómo Funciona

Autenticación

El proveedor utiliza el flujo OAuth2 Client Credentials. Clarive obtiene y gestiona automáticamente los tokens de acceso de Azure AD al realizar operaciones con archivos. No se requiere interacción del usuario.

Carga de Archivos

Cuando un usuario adjunta un archivo a un tópico:

  1. Clarive obtiene un token de acceso OAuth2 de Azure AD
  2. Se crea una sesión de carga fragmentada a través de la API de Microsoft Graph
  3. El archivo se carga en fragmentos de 3.2 MB
  4. El ID de archivo de SharePoint se almacena en la base de datos de Clarive para operaciones futuras
  5. Las jerarquías de carpetas se crean automáticamente según sea necesario

Descarga de Archivos

Cuando un usuario descarga un archivo adjunto:

  1. Se utiliza el ID de archivo de SharePoint almacenado para solicitar el contenido
  2. El archivo se transmite desde SharePoint a través de Clarive hasta el usuario
  3. Se preservan el nombre de archivo original y los metadatos

Eliminación de Archivos

Cuando se elimina un adjunto:

  1. El archivo se elimina de SharePoint usando su ID almacenado
  2. Para carpetas, el contenido se elimina recursivamente (primero archivos, luego carpetas)
  3. La operación es idempotente — eliminar un archivo inexistente no causa error

Características

  • Carga fragmentada — los archivos grandes se cargan en segmentos de 3.2 MB, soportando archivos de cualquier tamaño
  • Versionado nativo — SharePoint mantiene su propio historial de versiones de archivos; las versiones anteriores no se eliminan al actualizar
  • Creación automática de carpetas — las jerarquías de carpetas se crean automáticamente durante la carga
  • Saneamiento de nombres — los caracteres inválidos de SharePoint (" * : < > ? / \ |) se reemplazan automáticamente con guiones bajos
  • Codificación URL — los caracteres especiales como #, %, & se codifican correctamente
  • Manejo de conflictos — si ocurre un conflicto de nombres durante la carga, el proveedor reintenta con comportamiento de reemplazo
  • Limitación por ruta raíz — todas las operaciones pueden limitarse a una carpeta base, manteniendo los archivos de Clarive aislados
  • Soporte de accesos directos — los archivos de acceso directo .url en SharePoint se resuelven automáticamente al descargar

Servicios para Reglas

El módulo mssharepoint registra los siguientes servicios para su uso en reglas de Clarive (Diseñador de Reglas). Todos los servicios requieren que se seleccione un recurso SharePoint Site.

SharePoint: Upload Files

Carga un archivo o directorio local a SharePoint.

  • Local Path — ruta a un archivo o directorio local para cargar
  • Remote Folder — ruta de la carpeta destino en SharePoint (por defecto: /)

SharePoint: Download File

Descarga un archivo de SharePoint a un directorio local. El archivo se guarda con su nombre original del sitio remoto.

  • File Path or ID — la ruta del archivo remoto o el ID del elemento en SharePoint
  • Local Destination Directory — directorio local donde se guardará el archivo
  • Keep Remote Path — cuando está marcado y se usa una ruta de archivo (no un ID), recrea la estructura de directorios remota bajo el directorio local de destino. Por ejemplo, al descargar /Informes/2024/resumen.pdf con esta opción se crea <dir_local>/Informes/2024/resumen.pdf en lugar de <dir_local>/resumen.pdf

SharePoint: List Files

Lista archivos y carpetas en una ruta dada.

  • Path — la ruta de la carpeta de SharePoint a listar (por defecto: /)
  • Recursive — cuando está marcado, lista el contenido de subcarpetas recursivamente

SharePoint: Remove File or Folder

Elimina un archivo o carpeta de SharePoint. Las carpetas se eliminan recursivamente.

  • File Path or ID — la ruta del archivo remoto o el ID del elemento a eliminar

Crea un archivo de acceso directo .url en SharePoint que apunta a otro elemento.

  • Source Path or ID — el elemento al que apuntar
  • Destination Folder — dónde crear el acceso directo

SharePoint: Copy File or Folder

Copia un archivo o carpeta a otra ubicación en SharePoint. Las carpetas se copian recursivamente.

  • Source Path or ID — el elemento a copiar
  • Destination Folder — ruta del directorio destino

Limitaciones

  • Requiere conectividad de red desde el servidor Clarive a la API de Microsoft Graph (graph.microsoft.com)
  • El secreto de cliente de Azure AD tiene fecha de expiración; debe renovarse antes de que expire
  • El timeout HTTP por solicitud es de 300 segundos
  • El tamaño de fragmento es fijo en 3.2 MB
  • Solo una unidad (drive) por configuración de recurso (use múltiples recursos para múltiples unidades)
  • Las sesiones de carga no sobreviven un reinicio del servidor (no reanudables)
  • El rendimiento de descarga depende de los tiempos de respuesta de la API de Microsoft Graph

Resolución de Problemas

Errores de Autenticación (401 / 403)

  • Verifique que el Tenant ID, Client ID y Client Secret sean correctos
  • Compruebe que se haya otorgado el consentimiento de administrador para los permisos de API
  • Asegúrese de que el secreto de cliente no haya expirado

Archivo No Encontrado (404)

  • Verifique que el Site ID y Drive ID sean correctos
  • Compruebe que el Root Path existe en SharePoint
  • Si usa referencias basadas en ruta, verifique que no haya caracteres inválidos

Fallos en la Carga

  • Asegúrese de que el Registro de Aplicación tiene el permiso Files.ReadWrite.All
  • Verifique que la carpeta destino tenga permisos de escritura
  • Para archivos grandes, verifique que no haya un proxy o firewall limitando el tamaño de las solicitudes

Ver También