Acceso a datos en consultas genéricas mediante API basadas en contratos

Introducción

Las API basadas en contratos de Acumatica son muy potentes para seleccionar datos de las diversas entidades empresariales dentro de la plataforma Acumatica XRP. Acumatica proporciona una definición de punto final de servicios web para la mayoría de las entidades utilizadas en el sistema. Sin embargo, hay ocasiones en las que se necesitan datos que no tienen el formato de una entidad definida existente. Para resolver esta necesidad, puede crear Consultas genéricas (GI) para reunir datos de varias tablas formateados de manera que resulten útiles. Si se necesitan estos datos para la integración, es posible ampliar el punto final de servicios web para añadir una definición para estas consultas genéricas (GI). Esta entrada de blog explica cómo lograr este objetivo para los modelos de API basados en SOAP y REST.

Procederé a explicar esto mediante la creación de un caso de uso y los pasos de la solución para satisfacer la necesidad de ese caso de uso.

Caso práctico

En mi aplicación externa, necesito obtener las cantidades de inventario actuales de todos los artículos del almacén WHOLESALE.

Solución utilizando el Punto Final de Servicios Web por Defecto: Utilice la entidad Inventory Summary. Haga un bucle a través de cada número de Artículo de Inventario y llame a la API para la entidad InventorySummary una vez por cada artículo. Esto es extremadamente lento y consume muchos recursos porque requiere muchas llamadas múltiples a la API y por lo tanto a la base de datos.

Una solución mejor: Crear una Consulta Genérica para mostrar los datos necesarios para todos los elementos en un formulario de lista. A continuación, utilice la API para seleccionar registros de esta IG. Esto es mejor para el rendimiento porque podemos obtener cientos (o miles) de filas devueltas en una llamada.

Paso #1 - Crear la Consulta Genérica
En este ejemplo, he creado una IG llamada InventoryByLocation. Mostrará la Cantidad Disponible en Inventario para cada Artículo por WarehouseID y LocationID. Las siguientes 2 capturas de pantalla muestran la definición de la IG y los resultados de la consulta.

Paso #2 - Extender el Servicio Web Endpoint por defecto para añadir los campos GI
Aquí es donde debe tener cuidado. Configurar el endpoint correctamente hará que el proceso de llamarlo con la API sea mucho más fácil.

En primer lugar, debe ampliar el punto final predeterminado. Vaya al menú Integración, sección Preferencias, y elija el menú Puntos finales del servicio web. Seleccione el punto final predeterminado para la versión más reciente. En 2019 R1, la última versión es la 18.200.001.

A continuación, haga clic en EXTEND ENDPOINT en las acciones de la parte superior de la pantalla. Se le pedirá que cambie el nombre de su punto final extendido y que le dé una versión. Para este ejemplo, estoy usando MyExtEndpoint y la versión 18.200.001 (la misma que la versión del endpoint por defecto).

Cuando aparezca la pantalla, haga clic en INSERTAR. Esto le permitirá crear una nueva definición de entidad para la IG que fue creada. A continuación, tendrá que especificar el ID de pantalla - que era parte de la creación de la IG en el primer paso.

A continuación, tiene que añadir los campos al endpoint, lo que significa que tendrá que rellenar todas las columnas que se muestran en la IG. De esta forma, estarán disponibles para su uso en la API.

Tenga cuidado con este paso. Su primera inclinación será llenar todos los campos como se muestra en la imagen de abajo. Esto creará los campos en el nivel superior de la entidad InventoryByLocation.

Si configura el endpoint de esta manera, no podrá seleccionar ningún dato de la IG subyacente.

En su lugar, la forma de hacerlo correctamente es crear primero un nivel de Resultados bajo el nivel superior de la entidad, y luego rellenarlo con los campos. Esto se debe a que los Resultados son lo que se rellena en la IG cuando se ejecuta.

Inserte en el nivel de entidad InventoryByLocation, y luego Cree otra entidad debajo de ella llamada Result. Haga el ObjectName algo único. En este caso - InvByLocation es lo que elegí.

Por último, una vez creado este resultado, puede rellenarse con los campos de la IG. Este ejemplo se muestra a continuación.

Paso #3 - Acceda al Endpoint y a la Entidad en su código de integración.

Uso de SOAP

Ahora, en el código, es una tarea sencilla seleccionar los datos de la IG.

A continuación se muestra un breve ejemplo utilizando la API basada en SOAP y seleccionando todas las filas del resultado de la IG. Observe que la llamada Get estándar es la que funciona con la metodología SOAP. Observe cómo se solicita el Resultado, que es el nivel de detalle definido en el Endpoint.

  InventoryByLocation ToBeFound = new InventoryByLocation
   {
     Result = new InvByLocation[]
    {
       new InvByLocation { ReturnBehavior = ReturnBehavior.All }
    }
   };

   InventoryByLocation invByLoc = (InventoryByLocation)soapClient.Get(ToBeFound);

   foreach (InvByLocation InvRow in InvByLoc.Result)
   {
       ...process the results here…
   }

Uso de REST

Ahora, veamos la opción basada en REST. Hay una pequeña diferencia con esta opción. Voy a utilizar Postman para mostrar cómo hacer las llamadas.

En primer lugar, si intenta enviar una solicitud GET no funcionará. Observe el ejemplo de abajo - obtendrá un error BQL Delegate.

En su lugar, debe utilizar una solicitud PUT. Para realizar esta petición, especifique el endpoint, seguido del nombre de la IG(InventoryByLocation). Debido a que la IG sólo tiene Detalles - como se explica en la sección anterior basada en SOAP, también tendrá que añadir un parámetro de consulta "$expand=Resultado".

La solicitud PUT requiere que haya algo en el "Cuerpo" de la solicitud. Este debe estar vacío, por lo que deberá especificarlo con { }, como se muestra en el siguiente ejemplo.

Cuando ejecutes el "SEND" en esta petición PUT, obtendrás resultados JSON mostrando todos los detalles de la IG.

Para obtener información adicional sobre la creación de IG y el uso de las API de SOAP y REST, consulte la documentación de ayuda de Acumatica para Consultas genéricas y la documentación de ayuda de Referencia de API basada en contratos de Acumatica.

Resumen

Cuando se trata de sincronizar los datos entre Acumatica y sistemas de software externos, a menudo hay varias formas de realizar la tarea. Pero como desarrolladores, nos gusta que nuestras soluciones sean eficientes, escalables/de buen rendimiento y fáciles de mantener. La funcionalidad de consulta genéricade Acumatica nos permite crear consultas de base de datos específicas que pueden ayudarnos a alcanzar estos objetivos de rendimiento. El modelo Contract API permite la ampliación de los puntos finales del servicio web, de modo que podemos utilizar estas consultas genéricas para crear un número ilimitado de entidades a las que se puede acceder utilizando los últimos patrones y técnicas de software. Acumatica proporciona las herramientas y todo lo que tenemos que hacer es construir las soluciones.