Accès aux données dans les requêtes génériques à l'aide d'API basées sur les contrats

Introduction

Les API Acumatica basées sur les contrats sont très puissantes pour sélectionner les données des différentes entités commerciales au sein de la plateforme Acumatica XRP. Acumatica fournit d'emblée une définition des points de terminaison des services Web pour la plupart des entités utilisées dans le système. Cependant, il arrive que l'on ait besoin de données qui ne sont pas formatées comme une entité définie existante. Pour répondre à ce besoin, vous pouvez créer des requêtes génériques (IG) pour rassembler des données provenant de plusieurs tables et formatées d'une manière utile. Si ces données sont nécessaires à l'intégration, il est possible d'étendre le point de terminaison des services Web afin d'ajouter une définition pour ces requêtes génériques (GI). Cet article de blog explique comment atteindre cet objectif pour les modèles d'API basés sur SOAP et REST.

Je vais 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 mon application externe, je dois obtenir les quantités de stock actuelles pour tous les articles de l'entrepôt WHOLESALE.

Solution utilisant le point de terminaison des services Web par défaut : Utiliser l'entité Inventory Summary. Parcourez en boucle chaque numéro d'article en stock et appelez l'API de l'entité InventorySummary une fois pour chaque article. Cette méthode est extrêmement lente et consomme beaucoup de ressources car elle nécessite de nombreux appels à l'API et donc à la base de données.

Meilleure solution : Créer une demande générique pour afficher les données nécessaires pour tous les éléments dans un formulaire de liste. Utiliser ensuite l'API pour sélectionner des enregistrements à partir de cette IG. Cette solution est plus performante car elle permet d'obtenir des centaines (ou des milliers) de lignes en un seul appel.

Étape 1 - Créer l'enquête générique
Dans cet exemple, j'ai créé une IG appelée InventoryByLocation. Elle indiquera la quantité en stock pour chaque article par WarehouseID et LocationID. Les deux captures d'écran suivantes montrent la définition de l'IG et les résultats de l'enquête.

Étape 2 - Étendre le point de terminaison du service Web par défaut pour ajouter les champs IG
C'est ici que vous devez faire attention. La configuration correcte du point de terminaison facilitera grandement le processus d'appel à l'aide de l'API.

Tout d'abord, vous devez étendre le point de terminaison par défaut. Allez dans le menu Intégration, section Préférences, et choisissez le menu Points de terminaison du service Web. Sélectionnez le point de terminaison par défaut pour la dernière version. En 2019 R1, la dernière version est 18.200.001.

Ensuite, cliquez sur EXTEND ENDPOINT dans les 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 du point de terminaison par défaut).

Lorsque l'écran s'affiche, cliquez sur INSERT. Cela vous permettra de créer une nouvelle définition d'entité pour l'IG qui a été créée. Vous devrez alors spécifier l'ID de l'écran - qui faisait partie de la création de l'IG lors de la première étape.

Ensuite, vous devez ajouter les champs au point de terminaison, ce qui signifie que vous devez remplir toutes les colonnes affichées sur l'IG. De cette manière, elles seront disponibles pour être utilisées dans l'API.

Faites attention à cette étape. Vous aurez tout d'abord tendance à 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 de terminaison de cette manière, vous ne pourrez pas sélectionner de données dans l'IG sous-jacente.

Au lieu de cela, il faut d'abord créer un niveau "Résultats" sous le niveau supérieur de l'entité, puis remplir ce niveau avec les champs. En effet, ce sont les résultats qui sont renseignés dans l'IG lorsqu'elle est exécutée.

Insérer au niveau de l'entité InventoryByLocation, puis créer une autre entité en dessous appelée Result. Le nom de l'objet doit être unique. Dans ce cas, j'ai choisi InvByLocation.

Enfin, une fois ce résultat créé, il peut être renseigné avec les champs de l'IG. Cet exemple est illustré ci-dessous.

Étape 3 - Accédez au point final et à l'entité dans votre code d'intégration.

Utiliser SOAP

Maintenant, dans le code, il est facile de sélectionner les données de l'IG.

Vous trouverez ci-dessous un court exemple d'utilisation de l'API SOAP et de sélection de toutes les lignes du résultat de l'IG. Notez que l'appel standard Get est celui qui fonctionne avec la méthodologie SOAP. Remarquez que vous demandez le résultat, qui est le niveau de détail 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…
   }

Utiliser REST

Examinons maintenant l'option basée sur REST. Il y a une petite différence avec cette option. J'utiliserai Postman pour montrer comment effectuer les appels.

Tout d'abord, si vous essayez d'envoyer une requête GET, cela ne fonctionnera pas. Dans l'exemple ci-dessous, vous obtiendrez une erreur BQL Delegate.

Au lieu de cela, vous devez utiliser une requête PUT. Pour ce faire, vous devez spécifier le point de terminaison, suivi du nom de l'IG(InventoryByLocation). Comme l'IG n'a que des détails - comme expliqué dans la section SOAP ci-dessus - vous devrez également ajouter un paramètre de requête "$expand=Result".

La requête PUT nécessite la présence d'un élément dans le "corps" de la requête. Celui-ci doit être vide - vous le spécifierez donc avec { } comme indiqué dans l'exemple ci-dessous.

Lorsque vous exécutez la commande "SEND" de cette requête PUT, vous obtenez des résultats JSON contenant 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 Acumatica pour les demandes génériques et à la documentation d'aide Acumatica Contract-Based API Reference.

Résumé

Lorsqu'il s'agit de synchroniser les données entre Acumatica et des systèmes logiciels externes, il existe souvent plusieurs façons d'accomplir cette tâche. Mais en tant que développeurs, nous souhaitons que nos solutions soient efficaces, évolutives/performantes et faciles à maintenir. La fonctionnalité Generic Inquiryd'Acumatica nous permet de construire des requêtes de base de données spécifiques qui peuvent nous aider à atteindre ces objectifs de performance. Le modèle d'API contractuelle permet d'étendre les points de terminaison des services Web afin que nous puissions utiliser ces requêtes génériques pour créer un nombre illimité d'entités auxquelles il est possible d'accéder en utilisant les dernières techniques et modèles logiciels. Acumatica fournit les outils et tout ce que nous avons à faire est de construire les solutions.