Guide pratique pour ajouter une action ou une fonction Dataverse à votre application de code

Ce guide vous montre comment découvrir et ajouter des opérations Dataverse (actions et fonctions) à une application de code Power Apps à l’aide des commandes CLI find-dataverse-api et add-dataverse-api.

Prerequisites

• Une application de code Power Apps initialisée avec npx power-apps init
• @microsoft/power-apps version 1.1.1 ou ultérieure dans votre package.json
• Session CLI authentifiée (invite npx power-apps si nécessaire)
• Accès à l’environnement Dataverse contenant l’opération que vous souhaitez utiliser

Étape 1 : Découvrir les opérations disponibles

Permet find-dataverse-api de rechercher des opérations dans votre environnement par nom :

npx power-apps find-dataverse-api --search "WhoAmI"

La sortie répertorie les opérations correspondantes avec leur type (Action ou Fonction), les paramètres, l’entité de liaison (le cas échéant) et le type de retour :

====================================================================================================
Dataverse Operations
====================================================================================================

  WhoAmI  (Function)
  Returns: mscrm.WhoAmIResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Vous pouvez également rechercher des actions. Par exemple, pour rechercher l’action AddToQueue :

npx power-apps find-dataverse-api --search "AddToQueue"

====================================================================================================
Dataverse Operations
====================================================================================================

  AddToQueue  (Action)
  Bound to: mscrm.queue
  Parameters:
    - Target: mscrm.crmbaseentity
    - SourceQueue?: mscrm.queue
    - QueueItemProperties?: mscrm.queueitem
  Returns: mscrm.AddToQueueResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Pour obtenir le JSON brut (utile pour le script et pour les agents de codage), ajoutez --json:

npx power-apps find-dataverse-api --search "WhoAmI" --json

La recherche, ne respectant pas la casse, est une correspondance de sous-chaîne sur le nom de l’opération.

Étape 2 : Ajouter l’opération à votre application

Après avoir trouvé le nom de l’opération, exécutez la commande suivante :

npx power-apps add-dataverse-api --api-name WhoAmI
# or using the short alias:
npx power-apps add-dataverse-api -n WhoAmI

Commande :

1. Récupère la définition de l’opération à partir de Dataverse $metadatade votre environnement.
2. Écrit un fichier de schéma à l’adresse <schemaPath>/dataverse/WhoAmI.Schema.json.
3. Enregistre les fichiers de schéma pour toutes les entités Dataverse référencées par les paramètres ou le type de retour de l'opération, à moins qu'ils n'existent déjà.
4. Mises à jour power.config.json:
   • Ajoute databaseReferences["default.cds"] s’il n’est pas déjà présent.
   • Pour les opérations liées, ajoute l’entité de liaison à dataSources si elle n’est pas déjà présente.
5. Régénère dataSourcesInfo.ts pour inclure la nouvelle opération.
6. Génère un modèle typeScript et une classe de service sous <codeGenPath>/generated/.

En cas de réussite, vous voyez :

Dataverse API 'WhoAmI' added successfully.
Hint: Run 'npx power-apps run' to test locally, or 'npx power-apps push' to deploy.

Étape 3 : Utiliser le service généré dans votre code d’application

La commande génère une classe dédiée <ApiName>Service pour l’opération. Par exemple, après avoir ajouté WhoAmI, importez WhoAmIService à partir du répertoire des services générés :

import { WhoAmIService } from './generated/services/WhoAmIService';

Le service expose une méthode statique typée dont le nom est basé sur celui de l’opération. Par exemple:

const result = await WhoAmIService.WhoAmI();
// result.value contains: { BusinessUnitId: string, UserId: string, OrganizationId: string }

Pour une action liée telle que AddToQueue, le premier argument est toujours le GUID de l’enregistrement à utiliser :

import { AddToQueueService } from './generated/services/AddToQueueService';

const result = await AddToQueueService.AddToQueue(
  queueId,    // string (GUID of the destination queue)
  target,     // Record<string, unknown> (the activity to add)
  sourceQueue,         // Record<string, unknown> | undefined
  queueItemProperties  // Record<string, unknown> | undefined
);
// result.value contains: { QueueItemId: string }

Les types de paramètres et de retour proviennent du schéma Dataverse :

• Les paramètres GUID sont typés en tant que string.
• Les paramètres de recherche qui référencent une entité Dataverse sont typés en tant que Record<string, unknown>.
• Les opérations sans valeur de retour ne produisent pas de Promise<IOperationResult<void>>.
• Les opérations qui retournent un scalaire (par exemple, boolean, number) produisent Promise<IOperationResult<T>> avec le type TypeScript correspondant.
• Opérations qui retournent un type ou une entité complexe produisent Promise<IOperationResult<Record<string, unknown>>>.

Rerun pour effectuer la même opération à nouveau

Exécuter add-dataverse-api encore avec le même --api-name est sûr et idempotent :

• La commande remplace le fichier de schéma avec la dernière définition de Dataverse.
• Il régénère dataSourcesInfo.ts.
• Il supprime les entrées dupliquées dans power.config.json : elle n’ajoute pas de doublons.
• Il n’remplace pas les fichiers de schéma d’entité qui existent déjà.

Utilisez cette commande pour récupérer les modifications apportées à la signature d’une opération après une mise à jour dans l’environnement.

Fichiers créés ou modifiés

La add-dataverse-api commande crée ou met à jour les fichiers suivants dans votre projet :

Opérations liées et non liées

Les opérations liées sont limitées à un enregistrement d’entité spécifique. La méthode générée prend toujours un id: string paramètre comme premier argument, qui est le GUID de l’enregistrement à utiliser.

Les opérations non liées sont à l’échelle de l’environnement et ne nécessitent pas d’ID d’enregistrement. Leurs méthodes prennent uniquement les paramètres déclarés.

Les deux types sont ajoutés avec la même commande : l’interface CLI détecte automatiquement le type d’opération.

Résolution des problèmes

« Aucune opération trouvée » : la recherche est basée sur des sous-chaînes et ne respecte pas la casse, mais correspond uniquement au nom de l’opération. Essayez un terme plus court ou différent. Permet --json de confirmer la réponse brute.

Fichiers générés obsolètes : si vous avez renommé ou supprimé une opération et que les anciens fichiers générés restent, supprimez-les manuellement et réexécutez-les add-dataverse-api pour régénérer.

pac code add-data-source ignore l’action ou la fonction : les fichiers de schéma générés par add-dataverse-api utilisent un type Microsoft.PowerApps/dataverseOperation qui n’est pas reconnu par l’interface CLI PAC. Si des fichiers de schéma d’opération sont présents dans le dossier de schéma Dataverse, pac code add-data-source ignorez-les avec :

Skipping unsupported Dataverse operation schema '...AddRecurrence.Schema.json':

Ce comportement signifie que l'interface CLI PAC ne prend pas en charge le type de schéma Microsoft.PowerApps/dataverseOperation. Il ignore donc ces fichiers au lieu d'échouer. L’interface CLI PAC prend toujours en charge les autres fichiers de schéma qui représentent des sources de données d’entité Dataverse ou des connecteurs, et vous pouvez les ajouter à l’aide de pac code add-data-source.

Articles connexes

Utiliser des actions de l'API Web
Utiliser des fonctions API Web