Accès aux données dans les interrogations génériques à l’aide d’API contractuelles

Introduction

Les API basées sur des contrats Acumatica sont très puissantes dans la sélection des données des différentes entités commerciales au sein de la plate-forme Acumatica XRP. Acumatica fournit une définition de point de terminaison de services Web pour la plupart des entités utilisées dans le système. Cependant, il y a des moments où des données sont nécessaires qui ne sont pas formatées en tant qu’entité définie existante. Pour résoudre ce besoin, vous pouvez créer des interrogations génériques (GI) pour rassembler les données de plusieurs tables formatées d’une manière utile. Si ces données sont nécessaires pour l’intégration, il est possible d’étendre le point de terminaison des services Web pour ajouter une définition pour ces interrogations génériques (IG). Cet article de blog explique comment atteindre cet objectif pour les modèles d’API basés sur SOAP et REST.

Je vais continuer à expliquer cela en créant un cas d’utilisation et les étapes de la solution pour répondre aux besoins de ce cas d’utilisation.

Cas d’utilisation

Dans ma demande externe, j’ai besoin d’obtenir les quantités d’inventaire actuelles pour tous les articles dans l’entrepôt DE GROS.

Solution utilisant le point de terminaison des services Web par défaut : utilisez l’entité Inventory Summary. Parcourez chaque numéro d’article en stock et appelez l’API de l’entité InventorySummary une fois pour chaque article. C’est extrêmement lent et élevé sur l’utilisation des ressources car il nécessite tant d’appels multiples à l’API et donc à la base de données.

Meilleure solution : créez une enquête générique pour afficher les données nécessaires pour tous les éléments sous forme de liste. Ensuite, utilisez l’API pour sélectionner des enregistrements à partir de cette IG. C’est mieux pour les performances car nous pouvons obtenir des centaines (ou des milliers) de lignes retournées en un seul appel.

Étape #1 - Créer l’enquête générique
Dans cet exemple, j’ai créé un GI appelé InventoryByLocation. Il affichera la quantité disponible en stock pour chaque article par WarehouseID et LocationID. Les 2 captures d’écran suivantes montrent la définition du GI et les résultats de l’enquête.

Étape #2 – Étendez le point de terminaison de service Web par défaut pour ajouter les champs GI
C’est là que vous devez être prudent. La configuration correcte du point de terminaison rendra le processus d’appel avec l’API beaucoup plus facile.

Tout d’abord, vous devez étendre le point de terminaison par défaut. Accédez au menu d’intégration, section Préférences, et choisissez le menu Points de terminaison de service Web. Sélectionnez le point de terminaison par défaut pour la dernière version. Dans 2019 R1, la dernière version est 18.200.001.

Ensuite, cliquez sur ÉTENDRE LE POINT DE TERMINAISON à partir des actions en haut de l’écran. Il vous sera demandé de renommer votre point de terminaison étendu et de lui donner une version. Pour cet exemple, j’utilise MyExtEndpoint et la version 18.200.001 (identique à la version de point de terminaison par défaut).

Lorsque l’écran s’affiche, cliquez sur INSÉRER. Cela vous permettra de créer une nouvelle définition d’entité pour le GO qui a été créé. Vous devrez ensuite spécifier l’ID d’écran - qui faisait partie de la création de l’IG dans la première étape.

Ensuite, vous devez ajouter les champs au point de terminaison , ce qui signifie que vous devrez remplir toutes les colonnes affichées sur le GI. De cette façon, ils seront disponibles pour une utilisation dans l’API.

Soyez prudent avec cette étape. Votre première inclination sera de remplir tous les champs comme indiqué dans l’image ci-dessous. Cela créera les champs au niveau supérieur de l’entité InventoryByLocation .

Si vous configurez le point final de cette façon, vous ne pourrez sélectionner aucune donnée du GI fondamental.

Au lieu de cela, la façon de le faire correctement est de créer d’abord un niveau Résultats sous le niveau supérieur de l’entité, puis de le remplir avec les champs. C’est parce que les résultats sont ce qui obtient rempli sur le GI quand il est exécuté.

Insérez au niveau de l’entité InventoryByLocation , puis créez une autre entité en dessous appelée Résultat. Faites de l’ObjectName quelque chose d’unique. Dans ce cas - InvByLocation est ce que j’ai choisi.

Et enfin - une fois ce résultat créé, il peut être rempli avec les champs du GI. Cet exemple est illustré ci-dessous.

Étape #3 - Accédez au point de terminaison et à l’entité dans votre code d’intégration.

Utilisation de SOAP

Maintenant, dans le code, c’est une tâche simple de sélectionner les données du GI.

Vous trouverez ci-dessous un court exemple d’utilisation de l’API soap et de sélection de toutes les lignes à partir du résultat de l’IG. Notez que la norme Get call est ce qui fonctionne avec la méthodologie SOAP. Remarquez comment vous demandez le résultat, qui est le niveau de détails défini dans le point de terminaison.

  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…
   }

Utilisation de REST

Maintenant, regardons l’option basée sur REST. Il y a une petite différence avec cette option. Je vais utiliser Postman pour montrer comment faire les appels.

Tout d’abord, si vous essayez d’envoyer une demande GET si ne fonctionnera pas. Notez l’exemple ci-dessous - vous obtiendrez une erreur de délégué BQL.

Au lieu de cela, vous devez utiliser une demande PUT. Pour faire cette demande, vous spécifiez le point final, suivi du nom du GI (InventoryByLocation). Étant donné que l’IG n’a que des détails - comme expliqué dans la section basée sur SOAP ci-dessus, vous devrez également ajouter un paramètre de requête « $expand = Result ».

La demande PUT nécessite que quelque chose soit dans le « corps » de la demande. Cela doit être vide - vous allez donc le spécifier avec { } comme indiqué dans l’exemple ci-dessous.

Lorsque vous exécutez le « SEND » sur cette demande PUT, vous obtiendrez des résultats JSON montrant tous les détails de l’IG.

Pour plus d’informations sur la création d’IG et l’utilisation des API SOAP et REST, veuillez vous référer à la documentation d’aide d’Acumatica pour les demandes génériques et à la documentation d’aide de référence d’API basée sur contrat Acumatica.

Résumé

Lorsqu’il s’agit de synchroniser les données entre Acumatica et les systèmes logiciels externes, il existe souvent plusieurs façons d’accomplir la tâche. Mais en tant que développeurs, nous aimons que nos solutions soient efficaces, évolutives / performantes et faciles à entretenir. La fonctionnalité Generic Inquiry d’Acumatica nous permet de créer des requêtes de base de données spécifiques qui peuvent nous aider à atteindre ces objectifs de performance. Le modèle d’API de contrat permet l’extension des points de terminaison de service Web afin que nous puissions utiliser ces demandes génériques pour créer un nombre illimité d’entités qui peuvent ensuite être accessibles à l’aide des derniers modèles et techniques logiciels. Acumatica fournit les outils et tout ce que nous avons à faire est de construire les solutions.