Uno de los requerimientos más comunes que nos vamos a encontrar en nuestro día a día son las famosas entidades, ya todos conocemos y sabemos la importancia de estas y que básicamente nos sirven para carga masiva de datos, así como también para la exposición y consumo de los mismos, con el objetivo de que puedan ser utilizadas por terceros.

En más de una ocasión nos van a solicitar que las entidades que creemos sean públicas para que algún proveedor externo pueda consumirlas con el objetivo de recuperar datos e inclusive agregar o modificarlos dentro de D365, para ello, lo primero que es importante considerar, es que al crear nuestra entidad la propiedad Is Public se configure en Yes, y que configuremos la propiedad Public Collection Name con el nombre correspondiente por el cual se va a identificar dicha entidad por medio de OData.

Con esto aseguramos que la entidad quede expuesta, para ser consumida de forma externa por medio de OData.

Tal vez no estamos tan familiarizados con el termino OData, sin embargo, en términos generales podemos definirlo:

Como un protocolo para generar y consumir datos basado en la transferencia de estado representacional (REST) para las operaciones de creación, lectura, actualización y eliminación (CRUD). Al utilizar la arquitectura REST, se está utilizando el formato JavaScript Object Notation (JSON) para la recuperación y manipulación de datos.

Y ahora viene la pregunta del millón ¿cómo podemos consumir las entidades por medio de este protocolo? La manera más fácil y común que nosotros como desarrolladores tenemos para asegurarnos que nuestras entidades estén expuestas y puedan ser consumidas de forma correcta es probar a través de Postman, que es una herramienta que nos ofrece un conjunto de utilidades adicionales para poder gestionar las APIs de una forma más sencilla, entre estas opciones podemos crear peticiones HTTP sobre APIs, y de esta manera, probarlas.

Para realizar el consumo de nuestras entidades por medio de OData a través de Postman, debemos hacerlo en dos peticiones distintas, primero una petición que nos va a recuperar el token de acceso para poder consumirlas y después la petición que se desee para la manipulación de datos, para el primer paso es importante considerar lo siguiente:

Dynamics 365 usa la seguridad OAuth 2.0, la cual permite a una aplicación cliente obtener acceso autorizado a recursos protegidos como las API web. El flujo de código de autenticación requiere un agente de usuario que admita la redirección desde el servidor de autorización (la plataforma de identidad de Microsoft) a la aplicación, como se puede visualizar en la imagen abajo anexada.

Para ello el área de TI, nos tiene que proporcionar ciertos elementos que son importantes para poder generar nuestra solicitud de token: *Client Id: Id de la aplicación. *Secret Id: Clave secreta de aplicación. *Tenant Id: dominio del cliente.

Dichos elementos se obtienen de Azure, al registrar la aplicación que necesite tener acceso a D365, ese es un punto que de manera constante realiza el área de TI, de nuestros clientes.

Lo que sí es importante validar es que el identificador de la aplicación se encuentre configurado en D365, para ello nos vamos a la ruta:

Administración del sistema -> Configurar -> Aplicaciones de Azure Active Directory.

Dentro de dicha pantalla, filtramos por el campo Id de cliente, a partir del identificador de aplicación que nos fue proporcionado, y con ello validamos que se encuentre dado de alta para no tener problemas con el consumo desde terceros, en caso de no estar dicho registro, podemos agregarlo nosotros mismos a partir del botón nuevo, colocando el id de aplicación, un nombre que represente a la aplicación correspondiente, así como también un usuario especifico que servirá como identificación de la aplicación dentro de D365 F&O.

Una vez teniendo esto, podemos dirigirnos a POSTMAN, y agregar una solicitud nueva de tipo POST que va a ser necesaria para la generación de nuestro token, para ello colocamos como URL:

https://login.microsoftonline.com/[Colocar el tenant ID del cliente correspondiente]/oauth2/token?

Dicha URL, es la que nos va a permitir obtener el token correspondiente a nuestro ambiente requerido, es importante mencionar que como bien se puede observar en el link hay que colocar como parámetro el Tenant id del cliente para el cual estamos trabajando, este dato también debe ser proporcionado por su área de TI.

Ahora bien, en el body de petición debemos agregar las variables que a continuación se mencionarán para indicar hacía que ambiente se necesita el acceso y la aplicación que lo está solicitando.

• • grant_type: El valor de esta variable siempre debe ser client_Credentials.

• • client_Id: Id de aplicación que nos fue proporcionado con anterioridad.

• • client_secret: Clave secreta de la aplicación.

• • resource: URL del ambiente al que se requiere el acceso.

Una vez agregada esa información a la petición, simplemente le damos clic a enviar, y obtendremos como resultado el token de acceso correspondiente que podremos usar para consumir nuestras respectivas entidades, para ello simplemente hay que copiarnos el valor de la variable access_token.

Ahora bien, las peticiones más comunes que llegamos a probar a través de POSTMAN para el consumo de entidades por OData, son las siguientes:

Recuperación de datos:

Para recuperar los datos de una entidad, debemos generar una solicitud de tipo GET, con las siguientes características:

URL: [URL del ambiente donde vamos a recuperar la información]/data/[Public Collection Name de la entidad]?cross-company=true

Headers: Se agrega una variable llamada Authorization y en la columna Value, ponemos la palabra Bearer seguido del token generado anteriormente.

Al darle enviar, vamos a obtener como resultado el listado de datos, referente a esa entidad, en formato JSON.

Inserción de registros:

Para insertar registros se debe generar una petición de tipo POST con las siguientes características:

URL: [URL del ambiente en donde se van a insertar los registros]/data/[Public Collection Name de la entidad]

Headers: Se agrega una variable llamada Authorization y en la columna Value, ponemos la palabra Bearer seguido del token generado anteriormente.

Body: Se colocan los campos con sus valores correspondientes para el registro que se va a crear, esto en formato JSON.

Al darle enviar, vamos a obtener como resultado el código de mensaje «201 created», y vamos a tener el listado de campos y sus valores del registro creado, esto en formato JSON.

Actualización de registros:

Para insertar registros se debe generar una petición de tipo PATCH con las siguientes características:

URL: [URL del ambiente en donde se van a actualizar los registros]/data/[Public Collection Name de la entidad]([Parámetros para filtrar los registros a actualizar])?cross-company=true

Headers: Se agrega una variable llamada Authorization y en la columna Value, ponemos la palabra Bearer seguido del token generado anteriormente.

Body: Se colocan los campos a actualizar del registro con sus valores correspondientes, esto en formato JSON.

Al dar clic en enviar nos regresa un estatus 204, que indica que nuestra solicitud se ha realizado correctamente.

Eliminación de registros:

Para la eliminación de registros se debe generar una petición de tipo DELETE con las siguientes características:

URL: [URL del ambiente en donde se van a eliminar los registros]/data/[Public Collection Name de la entidad]([Parámetros para filtrar los registros a actualizar])?cross-company=true

Headers: Se agrega una variable llamada Authorization y en la columna Value, ponemos la palabra Bearer seguido del token generado anteriormente.

Al dar clic en enviar nos regresa un estatus 204, que indica que nuestra solicitud se ha realizado correctamente.

En conclusión, el probar la exposición y consumo de nuestras entidades es una práctica que debemos adoptar cada vez que nos pidan requerimientos de este tipo, para asegurar el correcto funcionamiento de las mismas, y su alcance desde terceros, por eso es importante conocer y tener claro como generar nuestras peticiones dependiendo de lo que se necesite y con base a eso sea más fácil ejecutar las pruebas de nuestro lado.