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

Introducción

Revisado: Ago, 2023

Las API basadas en contratos de Acumatica son muy potentes a la hora de seleccionar datos de las distintas entidades empresariales dentro de la plataforma Acumatica XRP. De serie, 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 ninguna entidad definida existente. Para resolver esta necesidad, se pueden crear consultas genéricas (GI) con el fin de recopilar datos de varias tablas con un formato que resulte útil. Si estos datos son necesarios para la integración, es posible ampliar el punto final de servicios web para añadir una definición de estas consultas genéricas (GI). En esta entrada del blog se explica cómo lograrlo tanto para los modelos de APIbasados en SOAP como paralos basados en 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 mediante el punto de conexión predeterminado de servicios web: utiliza la entidad «InventorySummary». Recorre cada número de artículo en stock y llama a la API de la entidad«InventorySummary»una vez por cada artículo. Este método es extremadamente lento y consume muchos recursos, ya que requiere numerosas llamadas 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 n.º 1: Crear la consulta genérica

En este ejemplo, he creado una consulta denominada«InventoryByLocation». Mostrará la cantidad disponible en stock de cada artículo por«WarehouseID» y«LocationID». Las dos capturas de pantalla siguientes muestran la definición de la consulta y los resultados de la misma.

Paso 2: Amplía el punto final del servicio web predeterminado para añadir los campos GI

Aquí es donde hay que tener cuidado. Si se configura correctamente el punto final, resultará mucho más fácil llamarlo mediante la API.

En primer lugar, debes ampliar el punto final predeterminado. Ve almenú «Integración», a la sección «Preferencias», y selecciona elmenú «Puntos finales de servicios web». Selecciona el punto final predeterminado de la última versión. En la versión 2019 R1, la última versión es la 18.200.001.

A continuación, haz clic en «EXTEND ENDPOINT» (Ampliar punto final) en el menú de acciones situado en la parte superior de la pantalla. Se te pedirá que cambies el nombre de tu punto final ampliado y que le asignes una versión. Para este ejemplo, voy a utilizar«MyExtEndpoint»y la versión 18.200.001 (la misma que la versión predeterminada del punto final).

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.

Ten cuidado con este paso. Tu primera reacción será rellenar todos los campos tal y como se muestra en la imagen siguiente. 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.

Insértalo en el nivel de la entidad«InventoryByLocation» y, a continuación, crea otra entidad debajo de ella llamada «Result». Elige unnombre de objetoque sea único. En este caso, he elegido«InvByLocation».

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, debes utilizar una solicitud PUT. Para realizar esta solicitud, debes especificar el punto final, seguido del nombre del GI (InventoryByLocation). Dado que el GI solo contiene «Detalles» —tal y como se explica en la sección anterior sobre SOAP—, también tendrás que añadir el parámetro de consulta«$expand=Result».

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

A la hora de sincronizar los datos entre Acumatica y sistemas de software externos, suele haber varias formas de llevar a cabo esta tarea. Pero, como desarrolladores, nos gusta que nuestras soluciones sean eficientes, escalables y de alto rendimiento, además de fáciles de mantener. La funcionalidad«Generic Inquiry»de Acumatica nos permite crear consultas específicas en la base de datos que nos ayudan a alcanzar estos objetivos de rendimiento. El modelode la API de contratospermite ampliarlos puntos finales del servicio web, de modo que podamos utilizar estas consultas genéricas para crear un número ilimitado de entidades a las que luego se puede acceder mediante los últimos patrones y técnicas de software. Acumatica nos proporciona las herramientas y lo único que tenemos que hacer es crear las soluciones.