Saltar a contenido

SharePoint

Una biblioteca de documentos de un sitio de SharePoint Online, sobre Microsoft Graph. Es el origen que más usan los ETL.

pip install "tai-storage[sharepoint]"
from tai_storage import StorageFactory

origin = StorageFactory.create_sharepoint()                       # todo del entorno
origin = StorageFactory.create_sharepoint(drive="Informes")       # otra biblioteca del sitio
origin = StorageFactory.create_sharepoint(site_path="teams")      # un sitio de Teams
Argumento Variable Qué es
tenant_id SHAREPOINT_TENANT_ID El tenant de Azure AD
client_id SHAREPOINT_CLIENT_ID El id de la aplicación registrada
client_secret SHAREPOINT_CLIENT_SECRET Su secreto
hostname SHAREPOINT_HOSTNAME contoso.sharepoint.com
site_name SHAREPOINT_SITE_NAME El nombre del sitio en su URL
drive SHAREPOINT_DRIVE (opcional) La biblioteca, por su nombre. Por defecto, la principal («Documentos»)
site_path — sites (por defecto) o teams, según la URL del sitio

Todo sale de la URL del sitio: https://contoso.sharepoint.com/sites/Ventas da hostname="contoso.sharepoint.com", site_path="sites" y site_name="Ventas".

La aplicación de Azure AD, sus permisos y cómo darle acceso a un único sitio están en La aplicación de Azure AD.

Un ETL típico

from tai_storage import StorageFactory

origin = StorageFactory.create_sharepoint(dev_mode=True)     # dev_mode solo mientras desarrollas

pendientes = origin.get_folder("Clientes/Entrada").list_files(pattern=r"\.xlsx$")
for file in pendientes:
    df = file.get_data().to_dataframe(sheet_name="Pedidos", entrypoint="Código")
    ...   # cargar df
    file.move_to(origin.get_file(f"Clientes/Procesados/{file.filename}"))

Lo que hace por ti

  • El token se renueva solo. MSAL lo cachea y lo pide de nuevo antes de que caduque (en torno a una hora). Si Graph responde 401, se pide un token nuevo una vez. Un 401 con el token nuevo es AuthenticationError: el secreto está revocado o caducado. Nunca se interpreta como que el fichero no existe.
  • Reintentos: los 429 y 5xx se reintentan hasta 5 veces, respetando Retry-After. Los cortes de red solo se reintentan en operaciones que se pueden repetir sin efectos.
  • Paginación: los listados siguen las páginas de Graph (200 elementos cada una).
  • Ficheros grandes: hasta 4 MiB, una petición. Por encima, una sesión de subida por trozos de 10 MiB, sin límite de tamaño. En la 0.1 todo iba en una sola petición, y Graph rechaza las de más de 250 MB.
  • Nombres: espacios, #, %, ñ y ' funcionan. Cada parte de la ruta se codifica.

Lo que hay que saber

  • Borrar manda a la papelera del sitio, de donde se puede recuperar.
  • Escribir por ruta crea las carpetas que falten.
  • copy_to() descarga y vuelve a subir. Graph tiene una copia asíncrona que no se usa porque obliga a esperar a un monitor.
  • move_to() dentro de la misma biblioteca es una operación de Graph, sin descargar nada.
  • El etag es el cTag de Graph: cambia solo cuando cambia el contenido, no al renombrar.
  • file.info.extra lleva item_id, web_url (el enlace para abrirlo en el navegador) y e_tag.

Cuánto cuesta cada operación

La primera operación, o connect(), pide el token y resuelve el sitio y la biblioteca: 2 o 3 peticiones, una vez por origen.

Operación Peticiones a Graph
exists(), metadatos 1 (0 si el fichero viene de un listado)
list_files() / list_folders() 1 por cada 200 elementos
list_files(recursive=True) lo anterior, por cada subcarpeta
read() / open_read() 2: los metadatos con la URL de descarga, y la descarga
escribir hasta 4 MiB 1
escribir más de 4 MiB 1 para abrir la sesión + 1 por cada trozo de 10 MiB
delete() de un fichero 2: comprobar que es un fichero y borrarlo
move_to() en la misma biblioteca 3
folder.create() 1 por cada carpeta que haya que crear
folder.delete() 1, más 1 para comprobar que existe y otra si no es recursive

Con configure_logger("DEBUG") se ve cada petición, con su estado y su duración (sin la query, que en las URL firmadas lleva el permiso).

Errores habituales

ConfigurationError: No existe el sitio …

SHAREPOINT_HOSTNAME, SHAREPOINT_SITE_NAME o site_path no coinciden con la URL del sitio. En un sitio de Teams la URL es /teams/<nombre>: pasa site_path="teams".

ConfigurationError: El sitio … no tiene la biblioteca 'X'

drive= no coincide con el nombre de ninguna biblioteca. El mensaje lista las que hay.

AuthenticationError

El tenant, el client id o el secreto no valen, o el secreto ha caducado. Se crea uno nuevo en Certificates & secrets de la aplicación.

PermissionDeniedError al listar o al escribir

La aplicación se autentica pero no tiene acceso a ese sitio. Con Sites.Selected hay que concedérselo sitio a sitio: paso 4. Si solo puede leer, el permiso del sitio es read y no write.

StorageUnavailableError con un 429

Microsoft está limitando las peticiones del tenant. La librería ya ha esperado y reintentado. Si persiste, baja la concurrencia del proceso.