Guide pratique pour connecter votre application de code à Dataverse (préversion)

Ce guide aide les développeurs à utiliser le Kit de développement logiciel (SDK) Power Apps pour connecter leur application de code à Microsoft Dataverse.

Note

Les fonctionnalités d'évaluation ne sont pas destinées à une utilisation en production et peuvent être restreintes. Ces fonctionnalités sont disponibles avant une publication officielle afin que les clients puissent obtenir un accès anticipé et fournir des commentaires.

Prerequisites

Kit sdk d’applications de code Power Apps @microsoft/power-apps - package npm
La version 1.46 ou plus récente de Power Apps CLI (PAC CLI)
Un environnement avec Dataverse activé
Vous devez être connecté à l’environnement à l’aide de l’interface CLI PAC

Étapes

Vérifiez que vous êtes connecté à votre environnement à l’aide de l’interface CLI PAC.
Utilisez la commande pac code add-data-source pour ajouter Dataverse en tant que source de données à votre application de code
```
pac code add-data-source -a dataverse -t <table-logical-name>
```
Remplacez <table-logical-name> par le nom logique de la table Dataverse à laquelle vous souhaitez vous connecter.

Scénarios pris en charge

Les scénarios suivants sont pris en charge lors de la connexion à Dataverse à l’aide du Kit de développement logiciel (SDK) Power Apps :

Ajouter des entités Dataverse à des applications de code à l’aide de l’interface CLI PAC
Effectuez des opérations CRUD :
- Créer
- Récupérer
- RetrieveMultiple
- Update
- Supprimer
Délégation pour :
- Filter
- Sort
- Requêtes Top
Prise en charge de la pagination

Configurer votre application de code

Avant d’effectuer des opérations de création, de lecture, de mise à jour et de suppression (CRUD) dans votre application de code, effectuez ces deux étapes d’installation.

Vérifier l’initialisation du Kit de développement logiciel (SDK) Power Apps avant les appels de données

Dans votre App.tsx fichier, implémentez une logique qui attend que le Kit de développement logiciel (SDK) Power Apps s’initialise entièrement avant d’effectuer des opérations de données. Cela empêche les erreurs provoquées par des services non initialisés ou un contexte manquant.

Utilisez une fonction asynchrone ou une gestion d’état pour confirmer l’initialisation avant d’effectuer des appels d’API. Par exemple:

useEffect(() => {
// Define an async function to initialize the Power Apps SDK
const init = async () => {
      try {
            await initialize(); // Wait for SDK initialization
            setIsInitialized(true); // Mark the app as ready for data operations
      } catch (err) {
            setError('Failed to initialize Power Apps SDK'); // Handle initialization errors
            setLoading(false); // Stop any loading indicators
      }
};

init(); // Call the initialization function when the component mounts
}, []);

useEffect(() => {
// Prevent data operations until the SDK is fully initialized
if (!isInitialized) return;

// Place your data reading logic here
}, []);

Importer les types et services requis

Lorsque vous ajoutez une source de données, les fichiers de modèle et de service sont automatiquement générés et placés dans le /generated/services/ dossier. Par exemple, si vous ajoutez la table Comptes intégrés en tant que source de données, les fichiers suivants sont créés :
- AccountsModel.ts : définit le modèle de données de la table Comptes.
- AccountsService.ts : fournit des méthodes de service pour interagir avec les données des comptes.
Vous pouvez les importer et les utiliser dans votre code comme suit :
```
import { AccountsService } from './generated/services/AccountsService';
import type { Accounts } from './generated/models/AccountsModel';
```

Créer des enregistrements

Créer l’objet d’enregistrement à l’aide du modèle généré

Les modèles générés reflètent le schéma de votre table Dataverse et doivent être utilisés pour créer des objets d’enregistrement.
Note

Lors de la création d’un enregistrement, excluez les colonnes gérées par le système ou en lecture seule, telles que les clés primaires et les champs de propriété. Parcourir les définitions de table dans votre environnement décrit un outil que vous pouvez utiliser pour comprendre quelles colonnes sont en lecture seule. Par exemple, dans la table Comptes, n’incluez pas les champs suivants :
- idcompte
- identifiant du propriétaire
- owneridname
- owneridtype
- owneridyominame
Formez un enregistrement avec uniquement les champs que vous souhaitez remplir. Par exemple, pour l’entité Comptes :
```
const newAccount = {
   name: "New Account"
   statecode: 0,
   accountnumber: "ACCOO1"
   ...
};
```

Envoyer l’enregistrement à l’aide du service généré

Utilisez les fonctions du fichier de service généré pour envoyer votre enregistrement. Par exemple, pour l’entité Comptes :

try {
const result = await AccountsService.create(newAccount as Omit<Accounts, 'accountid'>);

if (result.data) {
console.log('Account created:', result.data);
return result.data;
}
} catch (err) {
console.error('Failed to create account:', err);
throw err;
};

Lire les données

Vous pouvez récupérer un seul enregistrement ou composer une requête pour retourner plusieurs enregistrements.

Récupérer un enregistrement unique

Pour récupérer un enregistrement unique, vous avez besoin de sa clé primaire (par exemple, accountid).

const accountId = "<00000000-0000-0000-0000-000000000000>"; // Replace with actual ID value

try {
      const result = await AccountsService.get(accountId);
      if (result.data) {
            console.log('Account retrieved:', result.data);
      }
} catch (err) {
      console.error('Failed to retrieve account:', err);
}

Récupérer plusieurs enregistrements

Pour récupérer tous les enregistrements d’une table Dataverse, utilisez la getAll méthode suivante :

try {
   const result = await AccountsService.getAll();
   if (result.data) {
         const accounts = result.data;
         console.log(`Retrieved ${accounts.length} accounts`);
   }
} catch (err) {
   console.error('Failed to retrieve accounts:', err);
}

La getAll méthode accepte un paramètre facultatif qui implémente l’interface IGetAllOptions . Utilisez ces options pour personnaliser la requête :

interface IGetAllOptions {
   maxPageSize?: number;    // Maximum number of records per page
   select?: string[];       // Specific fields to retrieve
   filter?: string;         // OData filter string
   orderBy?: string[];     // Fields to sort by
   top?: number;           // Maximum number of records to retrieve
   skip?: number;          // Number of records to skip
   skipToken?: string;     // Token for pagination
}

Important

Limitez toujours le nombre de colonnes que vous récupérez avec le select paramètre.

Voici un exemple avec plusieurs options :

const fetchAccounts = async () => {
const options: IGetAllOptions = {
      select: ['name', 'accountnumber', 'address1_city'],
      filter: "address1_country eq 'USA'",
      orderBy: ['name asc'],
      top: 50
};

try {
      const result = await AccountsService.getAll(options);
      return result.data || [];
} catch (err) {
      console.error('Failed to fetch accounts:', err);
      return [];
}
};

Mettre à jour les enregistrements

Pour mettre à jour un enregistrement, vous avez besoin des éléments suivants :

Valeur de clé primaire de l’enregistrement. Par exemple, avec la table de compte, la valeur accountid.
Modifications que vous souhaitez apporter.

Important

Lorsque vous mettez à jour un enregistrement, incluez uniquement les propriétés que vous modifiez dans la requête. Il vous suffit de définir des propriétés modifiées d’un enregistrement que vous avez récupéré précédemment et d’inclure ces données dans votre demande met à jour toutes les propriétés même si leurs valeurs ne changent pas. Les fausses mises à jour comme celles-ci peuvent déclencher une logique métier qui s’attend à ce que les valeurs changent ou peuvent endommager les données d’audit pour indiquer qu’une personne a modifié les données qui n’ont pas changé.

Cet exemple met à jour les propriétés name et telephone1 de l’enregistrement de compte :

const accountId = "<your-account-guid>";
const changes = {
      name: "Updated Account Name",
      telephone1: "555-0123"
};

try {
      await AccountsService.update(accountId, changes);
      console.log('Account updated successfully');
} catch (err) {
      console.error('Failed to update account:', err);
}

Supprimer des enregistrements dans Dataverse

Pour supprimer un enregistrement, vous avez besoin de la valeur de clé primaire de l’enregistrement. Par exemple, avec la table de compte, la valeur accountid.

Par exemple:

const accountId = "<00000000-0000-0000-0000-000000000000>"; // Replace with actual ID value

try {
  await AccountsService.delete(accountId);
  console.log('Account deleted successfully');
} catch (err) {
  console.error('Failed to delete account:', err);
}

Scénarios non pris en charge

Les fonctionnalités suivantes ne sont pas encore prises en charge :

Récupération des valeurs mises en forme/noms affichés pour les ensembles d'options
Champs de recherche (y compris les recherches polymorphes)
Actions et fonctions Dataverse
Suppression de sources de données Dataverse via l’interface CLI PAC
Définition de schéma (métadonnées d’entité) CRUD
Prise en charge de FetchXML
Prise en charge des clés alternatives

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-10-08