Consultar tus proyectos de Autodesk con Data Management API
En la prueba de esta entrega pude entrar con Autodesk, pero el listado de proyectos no apareció hasta habilitar la integración en la cuenta. Es un buen punto de partida: reconocer al usuario era solo la primera parte. Ahora voy a utilizar Data Management API para consultar sus hubs, listar los proyectos y elegir uno. Al terminar, Issues Manager tendrá un proyecto comprobado contra Autodesk sobre el que continuar el trabajo.
Antes del proyecto aparece el hub
Autodesk organiza esta consulta en dos niveles: primero el hub y después los proyectos que contiene. En el caso de construcción que vamos a utilizar, el hub corresponde a la cuenta que agrupa esos proyectos. Si colaboras con varias organizaciones, puedes tener acceso a más de uno.
Imagina que trabajas en dos obras y ambas tienen un proyecto llamado «Coordinación». El nombre te ayuda a reconocerlo, pero la aplicación necesita saber también a qué cuenta pertenece. Por eso el selector comienza por el hub y muestra después sus proyectos. Así mantenemos el contexto de la elección.
Para obtener esa información utilizamos Data Management API, una de las APIs de Autodesk. Nos da el punto de partida para encontrar el proyecto; las consultas de incidencias vendrán después, mediante su API correspondiente. Tampoco conviene confundir este hub de construcción con el hub de desarrolladores de APS, donde gestionas tus aplicaciones y su acceso a las APIs.
Qué hay que habilitar para que aparezcan tus proyectos
Si vienes del artículo sobre el login con Autodesk, ya tienes una aplicación APS y un archivo de configuración privado. Para esta entrega mantenemos el mismo Client ID, el mismo secreto y la misma dirección de retorno. Lo que necesitamos ampliar es el acceso a los datos.
Comprueba que Data Management esté habilitada en tu aplicación APS. Después, el administrador de la cuenta de construcción debe añadir el Client ID en Account Admin → Custom integrations. La ubicación y el nombre del menú pueden variar según el producto. El dato que se registra es el Client ID: el Client Secret sigue guardado en el servidor y no se comparte con el lector ni con el navegador.
Esta configuración permite que la cuenta reconozca la integración. A continuación importa el acceso de la persona que inicia sesión: tiene que poder entrar en el proyecto y utilizar Docs → Files. Que una aplicación esté habilitada en una cuenta no convierte a sus usuarios en administradores ni les da acceso a todos sus proyectos.
Si no administras esa cuenta, necesitarás que alguien con los permisos correspondientes registre la integración. La guía de comprobaciones de Autodesk explica estos requisitos. Es un buen punto que revisar cuando el login funciona pero el proyecto no aparece.
Por qué Autodesk vuelve a pedir consentimiento
En la primera entrega pedíamos user-profile:read, el permiso para leer la identidad de la cuenta. Ahora añadimos data:read, que permite leer datos a los que esa cuenta tenga acceso. La demostración utiliza ese permiso para consultar hubs y proyectos; todavía no consulta archivos ni crea o modifica incidencias.
Si ya tenías la sesión de la versión anterior, desconecta Autodesk y vuelve a iniciar sesión para revisar y aceptar el nuevo consentimiento. Renovar el token anterior mantiene los permisos que ya habías concedido: no añade automáticamente este permiso de lectura.
El recorrido sigue pasando por FastAPI. El servidor guarda las credenciales de Autodesk, comprueba la sesión y renueva el token cuando hace falta. El navegador recibe los datos necesarios para mostrar la lista, sin recibir el token. La separación que hicimos en el login sigue sirviendo al añadir esta nueva consulta.
Del listado de Autodesk al selector de la aplicación
Una vez iniciada la sesión, Issues Manager pide al servidor la lista de hubs. Al elegir uno, consulta sus proyectos. Cada respuesta de Autodesk incluye más información de la que hace falta en un desplegable; la API de nuestra aplicación prepara una respuesta pequeña con el identificador y el nombre de cada recurso.
He separado el selector de la web, ProjectBrowser, de las consultas del servidor, ProjectService. Al cambiar de hub, la web borra el proyecto elegido: prefiero pedir una nueva selección a arrastrar una referencia que pertenecía a otra cuenta.
También hay que tener en cuenta la paginación. Autodesk puede entregar una colección en varias respuestas y facilitar un enlace para obtener la siguiente página. El servidor recorre esas páginas antes de preparar el listado. Una página vacía, por sí sola, no demuestra que hayamos llegado al final si todavía existe ese enlace.
Esta versión limita la selección a proyectos de construcción ACC/Forma. Data Management también trabaja con otros tipos de recursos, pero las APIs de incidencias no son intercambiables entre todos ellos. Los proyectos heredados de BIM 360 y otros tipos quedan fuera de este ejemplo; cuando se omiten recursos por ese motivo, la interfaz lo indica.
Primero se elige la cuenta de construcción; después, uno de sus proyectos accesibles.
Si tu proyecto no aparece, importa saber qué ha ocurrido
Una lista vacía y una consulta fallida necesitan respuestas distintas. Si Autodesk termina la consulta sin advertencias y no devuelve proyectos compatibles accesibles, la aplicación muestra ese resultado. Si deniega la petición, comunica el fallo para que puedas revisar los permisos o la configuración. Convertir ambos casos en un desplegable vacío te dejaría buscando un proyecto sin saber por dónde empezar.
Hay un tercer caso: Autodesk puede devolver resultados junto con advertencias. Al consultar hubs, por ejemplo, una advertencia puede corresponder a una región distinta de aquella en la que tienes acceso. La explicación oficial de Autodesk aclara que esto puede ocurrir incluso cuando la petición ha respondido correctamente.
Cuando Autodesk devuelve resultados parciales, muestro los proyectos disponibles junto con el aviso. Ocultar toda la lista haría perder resultados útiles; presentarla como completa podría llevarnos a concluir que el proyecto que buscamos no existe.
Si estás comprobando tu configuración, empieza por el consentimiento de lectura, la integración de la aplicación en esa cuenta y tu acceso a Docs. Si Autodesk informa de un límite temporal de consultas, espera antes de volver a intentarlo. Pulsar «Actualizar lista» continuamente no resuelve ese límite.
Seleccionar el nombre no basta para acreditar el acceso
El nombre es lo que ves en pantalla. El identificador es lo que utiliza la aplicación para pedir un recurso concreto. Conservamos el que devuelve Data Management, incluido su prefijo cuando lo tiene. Si más adelante otra API necesita un formato distinto, esa conversión se hará en la llamada que lo requiera.
La selección vuelve al servidor con los identificadores del hub y del proyecto. ProjectService.select consulta otra vez la colección accesible con esa conexión y busca allí el ID recibido. He mantenido esta segunda consulta porque una opción que vimos hace unos minutos en el navegador no es una autorización permanente. El método completo, salvo los comentarios, aparece al final de esta sección. Está en apps/api/app/projects/service.py: devuelve una selección si encuentra el ID y rechaza un recurso que no puede confirmar.
Esto también protege la ruta de la API. Una persona puede enviar un identificador directamente, sin utilizar la pantalla. Por tanto, esconder una opción o deshabilitar un botón no sustituye la comprobación en FastAPI. En la prueba real, la selección del proyecto de ejemplo Snowdon Towers respondió correctamente; una petición directa con un identificador ficticio recibió un 404 de recurso no disponible, sin datos del proyecto.
La selección se mantiene en esta pantalla y se pierde al recargar. De momento nos sirve para comprobar el contexto de lectura. Los permisos para consultar o modificar incidencias requieren sus propias comprobaciones, que abordaremos en el siguiente paso.
El mensaje de confirmación aparece después de volver a comprobar el acceso en Autodesk.
# Método de ProjectService; se omiten los comentarios.
def select(self, access: str, hub_id: str, project_id: str) -> Selection:
checked_id(project_id)
hub = self._hub(access, hub_id)
projects = self._projects(access, hub_id)
for project in projects.items:
if project.id == project_id:
return Selection(hub=hub, project=project)
if projects.incomplete:
raise ProjectFailure("aps_partial_response")
raise ProjectFailure("resource_unavailable", 404)
Llévate el código de la serie
Suscríbete a la newsletter de Código BIM y te enviaré el repositorio con las instrucciones para elegir la versión de cada artículo. Un mismo recurso para seguir toda la serie, desde el login con Autodesk hasta el futuro servidor MCP.
El correo incluye el acceso a todas las versiones de la serie. Podrás darte de baja de la newsletter cuando quieras.
Siguiente paso: quién puede hacer qué en el proyecto
Ya puedo elegir Snowdon Towers con una selección comprobada en el servidor. Ese proyecto será la referencia del siguiente paso: averiguar quién pertenece a él y qué permite hacer Autodesk con esa cuenta.
En la siguiente entrega, sobre miembros y permisos de Autodesk, consultamos los miembros y las capacidades que expone Autodesk para ese contexto. Eso nos permite preparar las operaciones con incidencias sobre permisos comprobados, antes de ofrecerlas también desde el futuro servidor MCP de la serie.
Respuestas