Vorgehensweise: Verbinden Ihrer Code-App mit Dataverse (Vorschau)

Dieses Handbuch hilft Entwicklern, das Power Apps SDK zum Verbinden ihrer Code-App mit Microsoft Dataverse zu verwenden.

Voraussetzungen

• Power Apps-Code-Apps-SDK @microsoft/power-apps - npm package
• Power Apps CLI (PAC CLI) Version 1.46 oder höher
• Eine Umgebung mit aktivierter Dataverse-Funktion
• Sie müssen mit der PAC CLI mit der Umgebung verbunden sein.

Steps

1. Stellen Sie sicher, dass Sie mithilfe der PAC CLI mit Ihrer Umgebung verbunden sind.

2. Verwenden des Befehls "Pac-Code-Add-Data-Source" zum Hinzufügen von Dataverse als Datenquelle zu Ihrer Code-App

   pac code add-data-source -a dataverse -t <table-logical-name>
   

   Ersetzen Sie <table-logical-name> durch den logischen Namen der Dataverse-Tabelle, mit der Sie eine Verbindung herstellen möchten.

Unterstützte Szenarien

Die folgenden Szenarien werden beim Herstellen einer Verbindung mit Dataverse mithilfe des Power Apps SDK unterstützt:

• Hinzufügen von Dataverse-Entitäten zu Code-Apps mithilfe der PAC CLI

• CRUD-Vorgänge durchführen:

  • Create
  • Gerätehandle
  • RetrieveMultiple
  • Update
  • Löschen

• Delegierung für:

  • Filter
  • Sort
  • Top-Abfragen

• Paging-Unterstützung

Richten Sie Ihre Code-App ein

Bevor Sie CruD-Vorgänge (Create, Read, Update, Delete) in Ihrer Code-App ausführen, führen Sie diese beiden Setupschritte aus.

1. Sicherstellen der Power Apps SDK-Initialisierung vor Datenaufrufen

   Implementieren Sie in Ihrer App.tsx Datei Logik, die wartet, bis das Power Apps SDK vollständig initialisiert wird, bevor Datenvorgänge ausgeführt werden. Dadurch werden Fehler verhindert, die durch nicht initialisierte Dienste oder fehlenden Kontext verursacht werden.

   Verwenden Sie eine asynchrone Funktion oder Zustandsverwaltung, um die Initialisierung zu bestätigen, bevor API-Aufrufe ausgeführt werden. Beispiel:

   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
   }, []);
   

2. Importieren erforderlicher Typen und Dienste

   Wenn Sie eine Datenquelle hinzufügen, werden Modell- und Dienstdateien automatisch generiert und im /generated/services/ Ordner platziert. Wenn Sie beispielsweise die integrierte Tabelle "Konten " als Datenquelle hinzufügen, werden die folgenden Dateien erstellt:

   • AccountsModel.ts – Definiert das Datenmodell für die Tabelle "Konten".

   • AccountsService.ts – Stellt Dienstmethoden für die Interaktion mit den Kontendaten bereit.

   Sie können diese in Ihrem Code wie folgt importieren und verwenden:

   import { AccountsService } from './generated/services/AccountsService';
   import type { Accounts } from './generated/models/AccountsModel';
   

Datensätze erstellen

1. Erstellen des Datensatzobjekts mithilfe des generierten Modells

   Die generierten Modelle spiegeln das Schema Ihrer Dataverse-Tabelle wider und sollten zum Erstellen von Datensatzobjekten verwendet werden.

   Hinweis

   Schließen Sie beim Erstellen eines Datensatzes vom System verwaltete oder schreibgeschützte Spalten wie Primärschlüssel und Besitzerfelder aus. Durchsuchen von Tabellendefinitionen in Ihrer Umgebung beschreibt ein Tool, mit dem Sie verstehen können, welche Spalten schreibgeschützt sind. Schließen Sie beispielsweise in der Tabelle "Konten" nicht die folgenden Felder ein:

   • accountid
   • Eigentümer-ID
   • owneridname
   • owneridtype
   • owneridyominame

   Erstellen Sie einen Datensatz mit nur den Feldern, die Sie auffüllen möchten. Wählen Sie beispielsweise die Entität „Konten“ aus:

   
   const newAccount = {
      name: "New Account"
      statecode: 0,
      accountnumber: "ACCOO1"
      ...
   };
   

2. Übermitteln des Datensatzes mithilfe des generierten Diensts

   Verwenden Sie die Funktionen in der generierten Dienstdatei, um Ihren Datensatz zu übermitteln. Wählen Sie beispielsweise die Entität „Konten“ aus:

   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;
   };
   

Daten lesen

Sie können einen einzelnen Datensatz abrufen oder eine Abfrage erstellen, um mehrere Datensätze zurückzugeben.

Abrufen eines einzelnen Datensatzes

Zum Abrufen eines einzelnen Datensatzes benötigen Sie den Primärschlüssel (z. B. 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);
}

Abrufen mehrerer Datensätze

Verwenden Sie die getAll Methode, um alle Datensätze aus einer Dataverse-Tabelle abzurufen:

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);
}

Die getAll Methode akzeptiert einen optionalen Parameter, der die IGetAllOptions Schnittstelle implementiert. Verwenden Sie diese Optionen, um die Abfrage anzupassen:

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
}

Hier ist ein Beispiel mit mehreren Optionen:

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 [];
}
};

Datensätze aktualisieren

Um einen Datensatz zu aktualisieren, benötigen Sie Folgendes:

1. Der Primärschlüsselwert des Datensatzes. Beispielsweise mit der Kontotabelle, den accountid-Wert.
2. Die Änderungen, die Sie vornehmen möchten.

In diesem Beispiel werden die name Und telephone1 Eigenschaften des Kontodatensatzes aktualisiert:

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);
}

Löschen von Datensätzen in Dataverse

Zum Löschen eines Datensatzes benötigen Sie den Primärschlüsselwert des Datensatzes. Am Beispiel der Kontotabelle ist der accountid-Wert zu nennen.

Beispiel:

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);
}

Nicht unterstützte Szenarien

Die folgenden Features werden noch nicht unterstützt:

• Abrufen formatierter Werte/Anzeigenamen für Optionssätze
• Nachschlagefelder (einschließlich polymorpher Nachschlagefelder)
• Dataverse Aktionen und Funktionen
• Löschen von Dataverse-Datenquellen über PAC CLI
• Schemadefinition (Entitätsmetadaten) CRUD
• FetchXML-Unterstützung
• Alternative Schlüsselunterstützung

Verwandte Informationen

• So verbinden Sie Ihre Code-App mit Daten
• Power Apps CLI