SharePoint¶
Una biblioteca de documentos de un sitio de SharePoint Online, sobre Microsoft Graph. Es el origen que más usan los ETL.
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
etages elcTagde Graph: cambia solo cuando cambia el contenido, no al renombrar. file.info.extrallevaitem_id,web_url(el enlace para abrirlo en el navegador) ye_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.