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

Introduction

Révision : août 2023

Les API basées sur les contrats d’Acumatica sont très performantes pour extraire des données des différentes entités métier au sein de la plateforme Acumatica XRP. D’emblée, 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 arrive parfois que l’on ait besoin de données qui ne correspondent pas au format d’une entité déjà définie. Pour répondre à ce besoin, vous pouvez créer des requêtes génériques (GI) afin de regrouper des données provenant de plusieurs tables, formatées de manière utile. Si ces données sont nécessaires à des fins d’intégration, il est possible d’étendre le point de terminaison des services Web pour y ajouter une définition de ces requêtes génériques (GI). Cet article de blog explique comment atteindre cet objectif pour les modèles d’APISOAP etREST.

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 par défaut des services Web : utilisez l'entité « InventorySummary ». Parcourez chaque référence 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 très gourmande en ressources, car elle nécessite de nombreux appels à l'API et, par conséquent, à 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 n° 1 – Créer la demande générale

Dans cet exemple, j'ai créé un GI nommé «InventoryByLocation ». Il affiche la quantité disponible en stock pour chaque article, en fonction deson « WarehouseID» et deson «LocationID ». Les deux captures d'écran suivantes présentent la définition du GI et les résultats de la requête.

Étape n° 2 – Étendre le point de terminaison du service Web par défaut pour ajouter les champs GI

C'est là qu'il faut faire attention. Une configuration correcte du point de terminaison facilitera grandement son appel via l'API.

Tout d'abord, vous devez mettre à jour le point de terminaison par défaut. Accédez aumenu « Intégration », puis à la section « Préférences », et sélectionnez lemenu « Points de terminaison des services Web ». Sélectionnez le point de terminaison par défaut correspondant à la dernière version. Dans la version 2019 R1, la dernière version est la 18.200.001.

Ensuite, cliquez sur « EXTEND ENDPOINT » (Étendre le point de terminaison) parmi les actions situées en haut de l'écran. Il vous sera demandé de renommer votre point de terminaison étendu et de lui attribuer une version. Dans cet exemple, j'utilise« MyExtEndpoint »et la version 18.200.001 (identique à la version par défaut du point de terminaison).

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.

Soyez vigilant lors de cette étape. Votre premier réflexe sera sans doute de remplir tous les champs comme indiqué sur 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érez-la au niveau de l'entité «InventoryByLocation», puis créez une autre entité sous celle-ci, nommée « Result ». Choisissez unnom d'objetunique. Dans ce cas précis, 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.

Vous devez plutôt utiliser une requête PUT. Pour effectuer cette requête, vous devez indiquer le point de terminaison, suivi du nom du GI (InventoryByLocation). Étant donné que le GI ne contient que des détails – comme expliqué dans la section consacrée au protocole SOAP ci-dessus –, vous devrez également ajouter le 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 de s’y prendre. Mais en tant que développeurs, nous souhaitons que nos solutions soient efficaces, évolutives, performantes et faciles à maintenir. La fonctionnalité« Generic Inquiry »d’Acumatica nous permet de créer des requêtes de base de données spécifiques qui nous aident à atteindre ces objectifs de performance. Le modèled’API Contractpermet d’étendreles points de terminaison des services Webafin que nous puissions utiliser ces requêtes génériques pour créer un nombre illimité d’entités, auxquelles il est ensuite possible d’accéder à l’aide des derniers modèles et techniques logiciels. Acumatica fournit les outils ; il ne nous reste plus qu’à élaborer les solutions.