Esta es la primera parte de dos, hablando sobre las Custom API que ofrece Dataverse. Que ¿qué son las Custom API?. Es una funcionalidad que ofrece Dataverse y que permite crear API para todas aquellas operaciones que no se cubren con las API estándar que ya vienen de caja. Se me ocurre por ejemplo operaciones o consultas complejas que no puedes ejecutar llamando a la API de la tabla Cuentas, o si necesitas customizar el cuerpo de la respuesta de la API. Te dejo un link con toda la documentación oficial.
Vamos a utilizar Postman para probar nuestras Custom API, por lo que te recomiendo que si no lo has leido aún te des una vuelta por el post en el que hablabamos de cómo autenticar llamadas a la API de Datarverse con OAuth.
En Dataverse la definición de las Custom API se almacenan (cómo no) en tablas. Esto significa que tanto la definición de las propiedades de la API que vamos a crear, como los parámetros de entrada (y sus propiedades), como los parámetros de salida (y sus propiedades) se van a almacenar en estas tablas. El diagrama de relaciones de las tablas es el siguiente:
Lo que hoy vamos a hacer es simplemente crear una Custom API que consulte una tabla customizada llamada Environments. Vamos al lío.
Lo primero que necesitamos hacer es crear la definición de nuestra Custom API. Para ello ve al portal de Power Apps, crea una nueva solución y añade un nuevo componente Custom API.
Se abrirá una nueva ventana con un formulario que nos pedirá cierta información. Lo que representa cada campo y sus particularidades lo puedes consultar aquí. Ojo que hay tema donde profundizar con esto.
Como yo para este post voy a crear una Custom API para consultar la tabla Environments dado el identificador del entorno, la configuración de la Custom API queda así:
Lo siguiente que vamos a hacer es crear los parámetros de entrada, y los parámetros de salida que devuelve la respuesta. Para ello repite la operación desde la solución que has creado: New, More, Other, Custom API Request Parameter. Al igual que antes se abrirá un nuevo formulario que nos pedirá la información relativa al parámetro que estamos creando. En mi caso, el parámetro de entrada que voy a recibir es el identificador de un entorno de tipo Guid, por lo que la configuración de mi único parámetro de entrada es la que puedes ver en esta imagen.
Repetimos la operación para crear el parámetro de salida: desde la solución que has creado selecciona New, More, Other, Custom API Response Parameter. Aparecerá el formulario de creación del parámetro que nos pedirá todos los campos necesarios. Mi API va a devolver un Environment que no es más que el registro de la tabla con el mismo nombre y por eso mi parámetro de salida es tipo Entity. En futuros post veremos algo mas complejo. El parámetro de salida que yo he definido tiene el aspecto de la imagen.
Ahora vamos con la parte que mas me gusta. El código. Manda narices que me dedique al low-code eh? Ya, yo también me sorprendo...
Venga al turrón. Abre Visual Studio o Visual Studio Code con lo que mas cómodo te sientas y crea un proyecto de tipo Bibilioteca de Clases. Cuando el proyecto esté creado ve al gestor de paquetes NuGet y añade la referencia Microsoft.CrmSdk.CoreAssemblies tal y como se puede ver en la siguiente imagen:
Abre la clase que se ha creado por defecto y renombrala a algo más qdescriptivo. Yo la he llamado APIController.cs. Esta API debe implementar la interfaz IPlugin así como su método Execute que va a recibir el contexto de la ejecución. Contexto que vamos a poder utilizar tanto para obtener los datos de la request, como para enviar la response, o como para crear conexión contra Dataverse si es necesario. Si has implementado antes Plugins de Dynamics (que supongo que si) seguro que todo esto te suena familiar. De todas formas aquí tienes la documentación oficial si necesitas mas información.
El código que yo he escrito tiene el siguiente aspecto. Como ves, obtenemos del ServiceProvider todo lo necesario para trabajar: servicio de trazas, contexto de ejecución y servicio de conexión a Dataverse.
Compila el proyecto y abre la herramienta PluginRegistrationTool (si no la has descargado, aquí cuentan como obtenerla). Inicia sesión en tu entorno de desarrollo y registra el nuevo ensamblado que acabas de crear seleccionando Register, Register New Assembly. Abre la librería compilada y haz clic en Register Selected Plugins.
Vámonos de vuelta a la solución que estamos creando en el portal de Power Platform y selecciona Add Existing, More, Developer, Plug-in Assembly y selecciona la librería que acabas de registrar en el paso anterior. Lo único que nos queda para poder invocar a nuestra Custom API es vincular el registro que hemos creado varios pasos atrás con la librería que acabamos de registrar. Para ello vuelve a la solución y selecciona tu Custom API y cuando se abra su formulario de edición, vincula la librería en el campo con nombre Plugin Type. En mi caso la configuración queda como puedes ver en la imagen de la izquierda.
¡En principio ya está todo listo! Abre una nueva request de Postman y configura la autenticación como comentamos en el post anterior. Cuando lo hayas hecho, introduce la url de tu entorno seguida del nombre de tu Custom API y de tu parámetro de entrada. En mi caso la url es la siguiente:
api/data/v9.2/bpp_GetEnvironment(bpp_EnvId=50afaa86-3654-ec11-8c62-000d3aa85535)Si todo ha ido bien, Postman deberia mostrar una salida parecida a esta:
En el siguiente post lo complicamos todo un poquito más. ¡¡Espero haber sido de ayuda!! ¡¡Hasta la próxima!!