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

The Acumatica Contract-based API’s are very powerful in selecting data from the various business entities within the Acumatica XRP platform. Out of the box, Acumatica provides a Web Services Endpoint definition for most of the entities used within the system. However, there are times when data is needed that is not formatted as an existing defined entity. To solve this need, you can create Generic Inquiries (GI’s) to pull together data from multiple tables formatted in a way that is useful. If this data is needed for integration, it is possible to extend the Web Services Endpoint to add a definition for these Generic Inquiries (GI’s). This blog post explains how to accomplish this goal for both the SOAP-based and REST-based API models.

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.