Erstellen einer Custom-API mit Lösungsdateien

Anmerkung

Dies ist ein erweitertes Thema, das davon ausgeht, dass Sie diese Themen bereits gelesen und verstanden haben:

• Benutzerdefinierte APIs erstellen und verwenden
• Erstellen Sie eine benutzerdefinierte API mit dem Plug-In-Registrierungstool

In diesem Artikel wird veranschaulicht, wie Sie eine benutzerdefinierte API erstellen, indem Sie einem Microsoft Dataverse Lösungsprojekt Definitionsdateien hinzufügen. Dieser Ansatz ist nützlich für Lösungsanbieter, die Lösungsdateien in der Quellcodeverwaltung speichern und ALM-Praktiken (Application Lifecycle Management) anwenden.

Verwenden Sie Microsoft Power Platform CLI, um das Lösungsprojekt zu initialisieren, das Lösungspaket zu erstellen und in eine Dataverse-Umgebung zu importieren. Sie müssen zuerst keine leere Lösung erstellen oder exportieren.

Prerequisites

• Installieren Sie Microsoft Power Platform CLI.
• Installieren Sie ein .NET SDK, das den dotnet Befehl enthält.
• Haben Sie Zugriff auf eine Dataverse-Umgebung, in der Sie über Berechtigungen zum Importieren von Lösungen verfügen.

Schritt 1: Initialisieren eines Lösungsprojekts

Führen Sie im Ordner, in dem Sie das Projekt erstellen möchten, den folgenden Befehl aus:

pac solution init --publisher-name Samples --publisher-prefix sample --outputDirectory CustomAPIExample

Der Befehl "pac solution init " erstellt einen CustomAPIExample Ordner, der Folgendes enthält:

• CustomAPIExample.cdsproj: Die Dataverse-Projektmappenprojektdatei.
• src\Other\Solution.xml: Die Lösungs- und Herausgeberdefinition.
• src\Other\Customizations.xml: Die Definition der Lösungsanpassungen.
• src\Other\Relationships.xml: Die Definition der Lösungsbeziehungen.

Der Ausgabeverzeichnisname wird zum eindeutigen Namen der Lösung. Überprüfen Sie die generierten Werte, src\Other\Solution.xml bevor Sie fortfahren.

Anmerkung

Der Herausgebername und das Anpassungspräfix müssen die anforderungen erfüllen, die für pac solution init beschrieben werden. Verwenden Sie Werte für einen vorhandenen Herausgeber in der Zielumgebung oder einen neuen Herausgeber, den Sie erstellen möchten.

Schritt 2: Hinzufügen der Definition der benutzerdefinierten API

Alle Custom-APIs in einer Lösung befinden sich in einem Ordner namens customapis. Innerhalb dieses Ordners befindet sich jede benutzerdefinierte API in einem Ordner, der nach der benutzerdefinierten API-Eigenschaft UniqueName benannt ist. Die Daten, die die benutzerdefinierte API darstellen, befinden sich in einer XML-Datei mit dem Namen customapi.xml.

1. Erstellen Sie im CustomAPIExample\src Ordner einen neuen Ordner mit dem Namen customapis.

2. Erstellen Sie im Ordner customapis einen Ordner mit der UniqueName der Custom-API, die Sie erstellen möchten. In diesem Beispiel verwenden wir sample_CustomAPIExample.

3. In dem Ordner sample_CustomAPIExample, den Sie erstellt haben, erstellen Sie eine Datei namens customapi.xml.

4. Bearbeiten Sie die Datei customapi.xml, um die Eigenschaften der benutzerdefinierten API festzulegen, die Sie erstellen möchten. Verwenden Sie in diesem Beispiel den folgenden XML-Code:

   <customapi uniquename="sample_CustomAPIExample">
     <allowedcustomprocessingsteptype>0</allowedcustomprocessingsteptype>
     <bindingtype>0</bindingtype>
     <boundentitylogicalname />
     <description default="A simple example of a custom API">
       <label description="A simple example of a custom API" languagecode="1033" />
     </description>
     <displayname default="Custom API Example">
       <label description="Custom API Example" languagecode="1033" />
     </displayname>
     <iscustomizable>0</iscustomizable>
     <executeprivilegename />
     <isfunction>0</isfunction>
     <isprivate>0</isprivate>
     <name>sample_CustomAPIExample</name>
     <plugintypeid />
   </customapi>
   

   Siehe die Informationen in Benutzerdefinierte API-Tabellenspalten, um die Werte der Elemente festzulegen.

Eine Beziehung zu einem Plug-In-Typ festlegen (optional)

Wenn Sie bereits über einen Plug-In-Typ verfügen, den Sie dieser benutzerdefinierten API zuordnen möchten, fügen Sie einen Verweis darauf in diese Definition ein, indem Sie das folgende Element innerhalb des <customapi> Elements hinzufügen:

<plugintypeid>
  <plugintypeexportkey>{Add the GUID value of the plug-in type export key}</plugintypeexportkey>
</plugintypeid>

oder

<plugintypeid>
  <plugintypeid>{Add the GUID value of the plug-in type ID}</plugintypeid>
</plugintypeid>

Anmerkung

Beide Werte funktionieren, wir empfehlen jedoch die Verwendung von plugintypeexportkey.

Verwenden Sie zum Abrufen der Werte "PluginTypeExportKey " und "PluginTypeId " eine Web-API-Abfrage, wenn Sie den Namen des Plug-In-Typs kennen:

GET [Organization Uri]/api/data/v9.2/plugintypes?$select=name,plugintypeid,plugintypeexportkey&$filter=contains(name,'MyPlugin.TypeName')

Schritt 3: Hinzufügen von benutzerdefinierten API-Anforderungsparametern

Schließen Sie Definitionen von Anforderungsparametern für die benutzerdefinierte API in einen Ordner ein, der aufgerufen wird customapirequestparameters. Innerhalb dieses Ordners befindet sich jeder benutzerdefinierte API-Anforderungsparameter in einem Ordner, der nach seiner UniqueName Eigenschaft benannt ist.

1. Wenn Ihre benutzerdefinierte API Über Anforderungsparameter verfügt, erstellen Sie innerhalb des CustomAPIExample\src\customapis\sample_CustomAPIExample Ordners einen Ordner mit dem Namen customapirequestparameters.

2. Erstellen Sie für jeden Custom-API-Anfrageparameter einen neuen Ordner mit der Eigenschaft UniqueName des Custom-API-Anfrageparameters. In diesem Beispiel verwenden wir StringParameter.

3. Fügen Sie im Ordner eine XML-Datei mit dem Namen customapirequestparameter.xmlhinzu.

4. Bearbeiten Sie die Datei customapirequestparameter.xml, um die Eigenschaften der Custom-API, die Sie erstellen möchten, festzulegen. In diesem Beispiel verwenden wir Folgendes:

   <customapirequestparameter uniquename="StringParameter">
     <description default="The StringParameter request parameter for custom API Example">
       <label description="The StringParameter request parameter for custom API Example" languagecode="1033" />
     </description>
     <displayname default="Custom API Example String Parameter">
       <label description="Custom API Example String Parameter" languagecode="1033" />
     </displayname>
     <iscustomizable>0</iscustomizable>
     <isoptional>0</isoptional>
     <logicalentityname />
     <name>sample_CustomAPIExample.StringParameter</name>
     <type>10</type>
   </customapirequestparameter>
   

   Siehe Spalten der Benutzerdefinierten API-Anforderungsparametertabelle , um die Werte der Elemente festzulegen.

Schritt 4: Hinzufügen von benutzerdefinierten API-Antworteigenschaften

Sie definieren Antworteigenschaften für die benutzerdefinierte API in einem Ordner mit dem Namen customapiresponseproperties. Jede benutzerdefinierte API-Antworteigenschaft befindet sich in einem eigenen Ordner, der nach dem Wert der Eigenschaft UniqueName benannt wird.

1. Wenn Ihre benutzerdefinierte API Antworteigenschaften enthält, erstellen Sie einen customapiresponseproperties Ordner in CustomAPIExample\src\customapis\sample_CustomAPIExample.

2. Erstellen Sie für jede Custom-API-Antwort-Eigenschaft einen neuen Ordner unter Verwendung der Eigenschaft UniqueName der Custom-API-Antwort-Eigenschaft. In diesem Beispiel verwenden wir StringProperty.

3. Fügen Sie dem Ordner eine XML-Datei hinzu, die benannt ist customapiresponseproperty.xml .

4. Bearbeiten Sie die Datei customapiresponseproperty.xml, um die Eigenschaften der Custom-API festzulegen, die Sie erstellen möchten. In diesem Beispiel verwenden wir Folgendes:

   <customapiresponseproperty uniquename="StringProperty">
     <description default="The StringProperty response property for custom API Example">
       <label description="The StringProperty response property for custom API Example" languagecode="1033" />
     </description>
     <displayname default="Custom API Example String Property">
       <label description="Custom API Example String Property" languagecode="1033" />
     </displayname>
     <iscustomizable>0</iscustomizable>
     <logicalentityname />
     <name>sample_CustomAPIExample.StringProperty</name>
     <type>10</type>
   </customapiresponseproperty>
   

   Informationen zum Festlegen der Werte der Elemente finden Sie in den Spalten der Benutzerdefinierten API-Antworteigenschaftstabellen.

Anmerkung

Obwohl das Schema für Anforderungsparameter und Antworteigenschaften sehr ähnlich ist, beachten Sie, dass isoptional für eine Antworteigenschaft nicht gültig ist und einen Fehler verursacht, wenn Sie versuchen, die Lösung zu importieren.

Schritt 5: Überprüfen der Projektstruktur der Lösung

Ihr Lösungsprojekt sollte diese Struktur aufweisen:

CustomAPIExample
|   CustomAPIExample.cdsproj
|
\---src
    +---customapis
    |   \---sample_CustomAPIExample
    |       |   customapi.xml
    |       |
    |       +---customapirequestparameters
    |       |   \---StringParameter
    |       |           customapirequestparameter.xml
    |       |
    |       \---customapiresponseproperties
    |           \---StringProperty
    |                   customapiresponseproperty.xml
    |
    \---Other
            Customizations.xml
            Relationships.xml
            Solution.xml

Schritt 6: Erstellen der Lösung

Führen Sie im CustomAPIExample Projektordner Folgendes aus:

dotnet build

Der Buildprozess stellt die erforderlichen Pakete wieder her und erstellt das nicht verwaltete Lösungspaket unter bin\Debug\CustomAPIExample.zip.

Schritt 7: Importieren der Lösung

Wichtig

Sie benötigen eine authentifizierte PAC CLI-Sitzung für die Dataverse-Umgebung.

Wenn Sie bereits über Authentifizierungsprofile verfügen, verwenden Sie pac-Authentifizierungsliste und pac-Authentifizierung , um das Profil für die Zielumgebung auszuwählen.

Wenn Sie über keine Authentifizierungsprofile verfügen, lernen Sie, eine Verbindung mit Ihrer Umgebung herzustellen.

1. Importieren und veröffentlichen Sie die Projektmappe aus dem CustomAPIExample Projektordner:

   pac solution import --path .\bin\Debug\CustomAPIExample.zip --publish-changes
   

Warten Sie, bis der Import abgeschlossen ist.

Anmerkung

Möglicherweise wird ein Fehler angezeigt, wenn gleichzeitig eine andere Lösung installiert wird. Weitere Informationen finden Sie unter "Gleichzeitige Lösungsvorgangsfehler". Die Auflösung besteht in der Regel darin, es später erneut zu versuchen.

Schritt 8: Überprüfen Sie, ob die Custom-API zu Ihrer Lösung hinzugefügt wurde

Öffnen Sie in Power Apps die CustomAPIExample-Lösung, und überprüfen Sie, ob die benutzerdefinierte API und die zugehörigen Anforderungsparameter und Antworteigenschaften enthalten sind.

Zu diesem Zeitpunkt können Sie Ihre API testen, indem Sie die unter " Testen Ihrer benutzerdefinierten API" beschriebenen Schritte verwenden. Zu diesem Zeitpunkt können Sie Ihre API testen, indem Sie die unter " Testen Ihrer benutzerdefinierten API" beschriebenen Schritte verwenden.

Aktualisieren einer Custom-API in einer Lösung

Nachdem Sie eine Lösung ausgeliefert haben, die eine Custom-API enthält, möchten Sie vielleicht einige Änderungen an der Custom-API in Ihrer nicht verwalteten Lösung vornehmen. Sie können neue Parameter oder Antworteigenschaften hinzufügen und Änderungen an den Spalten vornehmen, die eine Aktualisierung unterstützen, z. B. displayname und description.

Bevor Sie eine aktualisierte Lösung erstellen und importieren, legen Sie die Revision auf einen Wert fest, der größer als die bereits installierte Version ist. Führen Sie beispielsweise diese Befehle aus dem Projektmappenordner aus:

pac solution version --revisionversion 2 --solutionPath .\src
dotnet build
pac solution import --path .\bin\Debug\CustomAPIExample.zip --publish-changes

Wichtig

Sie können keine Änderung an einer Custom-API in einer Lösung vornehmen, die eine der Eigenschaften verändert, die nach dem Speichern nicht mehr geändert werden können. Wenn Sie eine neuere Version einer Lösung installieren, die eine Definition einer Custom-API enthält, wird versucht, die Custom-API, die Custom-API-Anfrageparameter und die Custom-API-Antworteigenschaften zu aktualisieren. Eine Lösungsaktualisierung ist dasselbe wie der Versuch, die Custom-API mit einer beliebigen anderen Methode zu aktualisieren.

Im Folgenden finden Sie Eigenschaften in den Lösungsdateien, die nicht mehr geändert werden können, nachdem eine Custom-API erstellt wurde:

• Benutzerdefinierte API-Eigenschaften
  • allowedcustomprocessingsteptype
  • bindingtype
  • boundentitylogicalname
  • isfunction
  • uniquename
  • workflowsdkstepenabled
• Eigenschaften des benutzerdefinierten API-Anforderungsparameters:
  • isoptional
  • logicalentityname
  • type
  • uniquename
• Eigenschaften der benutzerdefinierten API-Antworteigenschaft:
  • logicalentityname
  • type
  • uniquename

Weitere Informationen finden Sie in CustomAPI-Tabellen. Weitere Informationen finden Sie in CustomAPI-Tabellen.

Bereitstellen lokalisierter Bezeichnungen mit der Lösung

Anstatt den in lokalisierten Bezeichnungswerten beschriebenen Prozess zu verwenden, können Sie Übersetzungen direkt in den Lösungsdateien für benutzerdefinierte API-Entitäten bereitstellen. Wenn Sie beispielsweise japanische lokalisierte Bezeichnungen für Ihre benutzerdefinierte API bereitstellen möchten, können Sie sie für die und displayname die description Eigenschaften bereitstellen, wie im folgenden Beispiel gezeigt:

<customapi uniquename="sample_CustomAPIExample">
  <allowedcustomprocessingsteptype>0</allowedcustomprocessingsteptype>
  <bindingtype>0</bindingtype>
  <description default="A simple example of a custom API">
    <label description="A simple example of a custom API" languagecode="1033" />
    <label description="カスタムAPIの簡単な例" languagecode="1041" />
  </description>
  <displayname default="Custom API Example">
    <label description="Custom API Example" languagecode="1033" />
    <label description="カスタムAPIの例" languagecode="1041" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <isfunction>0</isfunction>
  <name>sample_CustomAPIExample</name>
</customapi>

Siehe auch

• Benutzerdefinierte APIs erstellen und verwenden
• CustomAPI-Tabellen
• Erstellen Sie eine benutzerdefinierte API mit dem Plug-In-Registrierungstool
• Erstellen Sie eine angepasste Custom-API in Power Apps
• Eine benutzerdefinierte API mit Code erstellen
• Eigene Nachrichten erstellen
• Microsoft Power Platform CLI-Lösungsbefehlsgruppe