Erstellen einer Custom-API mit Lösungsdateien

  • Artikel

Hinweis

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

Während Sie Custom-APIs über einen Designer oder mit Code erstellen können, können Sie sie auch durch die Arbeit mit Dateien innerhalb einer Lösung definieren. Die Verwendung von Dateien in einer Lösung ist möglicherweise die bevorzugte Option für Lösungsherausgeber, die die empfohlenen Best Practices für Application Lifecycle Management (ALM) anwenden.

Eine Lösungsdatei ist eine komprimierte Datei (ZIP), die aus einer Microsoft Dataverse-Instanz exportiert wurde. Der Inhalt dieser Datei kann extrahiert und die Komponenten in ein Quell-Repository eingecheckt werden. Der Inhalt kann bearbeitet und anschließend erneut komprimiert werden. Die auf die Lösung vorgenommenen Änderungen sind Teil der Lösung und werden beim Importieren der Lösung erstellt.

Hinweis

Diese Prozesse werden normalerweise mit Tools und Prozessen automatisiert. Dies wird in diesem Thema jedoch nicht abgedeckt. Dieses Thema konzentriert sich auf das einfache Szenario des Erstellens einer Custom-API durch manuelle Manipulation der extrahierten Dateien in einer Lösung, um zu zeigen, wie die Daten in den Dateien zum Erstellen einer Custom-API verwendet werden können. Weitere Informationen: Steuerelemente mit Lösungsdateien

Schritt 1: Eine nicht verwaltete Lösung erstellen

Sie sollten nicht versuchen, eine Lösungsdatei manuell zu erstellen. Verwenden Sie die Tools in Power Apps, um eine Lösungsdatei zu generieren. Führen Sie die Schritte in den folgenden Artikeln aus, um eine Lösung zu erstellen und zu exportieren. Die Lösung muss keine Lösungskomponenten enthalten.

  1. Lösung erstellen

    In diesem Beispiel wird die Lösung einfach wie folgt definiert:

    Eine leere Lösung.

  2. Lösungen exportieren

    Stellen Sie in diesem Beispiel sicher, dass Sie eine nicht verwaltete Lösung exportieren. Verwaltete Lösung ist die Standardeinstellung.

    Option zur Auswahl zum Exportieren einer nicht verwalteten Lösung.

Sie finden die exportierte Datei in Ihrem Downloadordner. In diesem Fall hängt der Name vom Namen und der Version der Lösung ab: CustomAPIExample_1_0_0_2.zip.

Schritt 2: Inhalt der Lösung extrahieren und Version aktualisieren

Die Lösung ist eine komprimierte Datei (ZIP).

  1. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie Alle extrahieren... aus dem Kontextmenü aus.

    Sie sollten nur die folgenden drei Dateien im Ordner sehen:

    • [Content_Types].xml
    • customizations.xml
    • solution.xml

  2. Öffnen Sie die Datei „solution.xml“, und suchen Sie das Element Version.

    <ImportExportXml version="9.1.0.23474" SolutionPackageVersion="9.1" languagecode="1033" generatedBy="CrmLive" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SolutionManifest>
    <UniqueName>CustomAPIExample</UniqueName>
    <LocalizedNames>
      <LocalizedName description="Custom API Example" languagecode="1033" />
    </LocalizedNames>
    <Descriptions />
    <Version>1.0.0.1</Version>

  3. Aktualisieren Sie den Wert um 1. In diesem Beispiel lautet er <Version>1.0.0.2</Version>.

  4. Speichern Sie die Datei.

Schritt 3: Fügen Sie die Definition der Custom-API hinzu

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

  1. Erstellen Sie in dem Ordner mit den extrahierten Dateien 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. In diesem Beispiel verwenden wir die folgende XML-Datei:

    <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 einen Plug-in Typ haben, den Sie mit dieser Custom-API verknüpfen möchten, können Sie einen Verweis darauf in diese Definition aufnehmen, indem Sie das folgende Element innerhalb des Elements <customapi> 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>

Hinweis

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

Sie können die PluginTypeExportKey- und PluginTypeId-Werte mithilfe einer Web-API-Abfrage wie dieser abrufen, bei der 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 4: Hinzufügen beliebiger angepasster API-Anfrageparameter

Alle Definitionen von Anfrageparametern für die Custom-API sind in einem Ordner namens customapirequestparameters enthalten. Innerhalb dieses Ordners befindet sich jeder Custom-API-Anfrageparameter in einem Ordner, der nach der Eigenschaft UniqueName des Custom-API-Anfrageparameters benannt ist.

  1. Wenn Ihre Custom-API über Abfrageparameter verfügt, erstellen Sie in dem Ordner für die Custom-API, den Sie im vorherigen Schritt erstellt haben, 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 innerhalb des Ordners eine XML-Datei mit dem Namen customapirequestparameter.xml hinzu.
  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 die Informationen in CustomAPIRequestParameter Tabellenspalten, um die Werte der Elemente festzulegen.

Schritt 5: Hinzufügen beliebiger angepasster API Response Properties

Alle Definitionen von Antworteigenschaften für die Custom-API sind in einem Ordner mit dem Namen customapiresponseproperties enthalten. Innerhalb dieses Ordners befindet sich jede Custom-API-Antworteigenschaft in einem Ordner, der nach der Eigenschaft UniqueName der Custom-API-Antworteigenschaft benannt ist.

  1. Wenn Ihre Custom-API über Antwort-Eigenschaften verfügt, erstellen Sie in dem Ordner für die Custom-API, den Sie in Schritt 3: Hinzufügen der Definition der Custom-API erstellt haben, einen Ordner mit dem Namen customapiresponseproperties.
  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 innerhalb des Ordners eine XML-Datei mit dem Namen customapiresponseproperty.xml hinzu.
  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>

Siehe die Informationen in CustomAPIResponseProperty Table Columns, um die Werte der Elemente festzulegen.

Hinweis

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 6: Dateien komprimieren, um eine neue Lösungsdatei zu erstellen

  1. Kehren Sie zu dem Ordner zurück, in den Sie die ursprüngliche Lösungsdatei im Zuge von Schritt 2: Inhalt der Lösung extrahieren und Version aktualisieren extrahiert haben.

  2. Wählen Sie alle extrahierten Dateien und den Ordner customapis, den Sie erstellt haben, aus.

    Die ausgewählten Lösungsdateien.

  3. Klicken Sie mit der rechten Maustaste auf die ausgewählten Dateien, und wählen Sie Senden an > Komprimierter (gezippter Ordner) aus.

  4. Sie können die resultierende Datei beliebig umbenennen. Benennen Sie sie in diesem Beispiel so um, dass sie mit der ursprünglich exportierten Lösungsdatei übereinstimmt: CustomAPIExample_1_0_0_2.zip.

Schritt 7: Importieren Sie die Lösung mit der Definition Ihrer Custom-API

  1. Kehren Sie zu Power Apps zurück, und wählen Sie Lösungen aus.

  2. Wählen Sie Importieren aus, und folgen Sie den Anweisungen, um die Lösungsdatei auszuwählen, die Sie im vorherigen Schritt erstellt haben.

    Die Lösungsdatei importieren.

    Hinweis

    Wenn Sie eine Warnung wie Diese Version des Lösungspakets ist bereits installiert sehen, darf das Version-Element der Datei „solution.xml“ nicht wie in Schritt 2: Inhalt der Lösung extrahieren und Version aktualisieren beschrieben aktualisiert sein.

  3. Es sollte eine Warnung wie Dieses Lösungspaket enthält ein Update für eine bereits installierte Lösung angezeigt werden. Wählen Sie zum Fortfahren Importieren.

  4. Warten Sie einige Minuten, bis der Lösungsimport abgeschlossen ist.

Hinweis

Möglicherweise wird ein Fehler angezeigt, wenn gleichzeitig eine andere Lösung installiert wird. Weitere Informationen: Das Installieren oder Entfernen der Lösung ist fehlgeschlagen, da gleichzeitig eine andere Lösung installiert oder entfernt wurde.

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

Öffnen Sie die von Ihnen erstellte Lösung und überprüfen Sie, ob die Custom-API und die zugehörigen Anfrageparameter und Antworteigenschaften enthalten sind.

Zeigt, dass die Lösungskomponente erfolgreich installiert wurde.

Zu diesem Zeitpunkt können Sie Ihre API anhand der in Testen Sie Ihre Custom-API beschriebenen Schritte testen.

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.

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
  • Benutzerdefinierte API RequestParameter-Eigenschaften
    • isoptional
    • logicalentityname
    • type
    • uniquename
  • Benutzerdefinierte API-Antworteigenschaften:
    • logicalentityname
    • type
    • uniquename

Weitere Informationen: CustomAPI-Tabellen

Lokalisierte Beschriftungen in der Lösung bereitstellen

Alternativ zu dem unter Lokalisierte Label-Werte beschriebenen Prozess können Sie, wenn Sie die Lösungsdateien für Custom-API-Entitäten bearbeiten, die Übersetzungen direkt in diesen Dateien bereitstellen. Wenn Sie zum Beispiel japanischsprachige Labels für Ihre Custom-API bereitstellen möchten, können Sie diese für die Eigenschaften description und displayname bereitstellen, wie unten 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

Custom-APIs erstellen und verwenden
CustomAPI-Tabellen
Erstellen Sie eine Custom-API mit dem Tool zur Plugin-Registrierung
Erstellen Sie eine Custom-API in Power Apps
Erstellen Sie eine Custom-API mit Code
Eigene Nachrichten erstellen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).