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

Introduction

Révision : août 2023

Les API basées sur les contrats d'Acumatica sont très efficaces pour sélectionner des données parmi les différentes entités d'affaires de la plateforme Acumatica XRP. Par défaut, 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 que des données soient nécessaires sans être formatées comme une entité définie. Pour répondre à ce besoin, vous pouvez créer des requêtes génériques (RG) afin de rassembler des données provenant de plusieurs tables, formatées de manière exploitable. Si ces données sont nécessaires à l'intégration, il est possible d'étendre le point de terminaison des services Web pour y ajouter une définition pour ces requêtes génériques (RG). Cet article de blogue explique comment procéder pour les modèles d'API 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 : utiliser l’entité « Résumé de l’inventaire ». Parcourir chaque numéro d'article et appeler l'API de l'entité « Résumé de l'inventaire » une fois pour chaque article. Cette méthode est extrêmement lente et gourmande en ressources car elle nécessite de nombreux appels à 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 la demande générique

Dans cet exemple, j'ai créé un inventaire global (IG) appelé InventoryByLocation . Il affichera la quantité en stock pour chaque article, en fonction de l'identifiant d'entrepôt (WarehouseID) et de l' identifiant d'emplacement (LocationID) . Les deux captures d'écran suivantes illustrent la définition de l'IG et les résultats de la requête.

Étape #2 – Étendre le point de terminaison Web Service par défaut pour ajouter les champs GI

C’est là qu’il faut faire attention. Configurer correctement le point de terminaison rendra le processus d’appel avec l’API beaucoup plus facile.

Vous devez d'abord mettre à jour le point de terminaison par défaut. Accédez au menu Intégration , section Préférences, puis sélectionnez Points de terminaison de service Web . Choisissez la version la plus récente du point de terminaison par défaut. Dans la version 2019 R1, c'est la version 18.200.001.

Ensuite, cliquez sur ÉTENDRE LE POINT DE TERMINAL parmi les actions en haut de l'écran. Vous serez invité à renommer votre point de terminaison étendu et à lui attribuer une version. Dans 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 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.

Faites attention à cette étape. Votre premier réflexe 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 l'entité au niveau InventoryByLocation , puis créez une autre entité nommée Result en dessous. Attribuez-lui un nom unique. Dans cet exemple, j'ai choisi InvByLocation .

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.

Vous devez utiliser une requête PUT. Pour ce faire, précisez le point de terminaison, suivi du nom de l'inventaire géographique ( InventoryByLocation ). Comme cet inventaire ne contient que des détails (comme expliqué dans la section SOAP ci-dessus), vous devrez également ajouter le 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 des systèmes logiciels externes, plusieurs méthodes existent. En tant que développeurs, on privilégie des solutions performantes, évolutives et faciles à maintenir. La fonctionnalité de requêtes génériques d'Acumatica nous permet de créer des requêtes de base de données spécifiques, contribuant ainsi à atteindre ces objectifs de performance. Le modèle d'API Contract permet d'étendre les points de terminaison des services Web, ce qui nous permet d'utiliser ces requêtes génériques pour créer un nombre illimité d'entités, accessibles ensuite grâce aux dernières technologies et méthodes logicielles. Acumatica fournit les outils ; il ne nous reste plus qu'à concevoir les solutions.