Erstellen Sie eine benutzerdefinierte API mithilfe des Plug-In-Registrierungstools

Erstellen Sie eine benutzerdefinierte API mithilfe des Designers im Plug-In-Registrierungstool (PRT). In diesem Artikel wird gezeigt, wie Sie eine benutzerdefinierte API definieren, Anforderungsparameter und Antworteigenschaften hinzufügen und diese anzeigen, aktualisieren oder löschen können. Das PRT ist eine Windows Clientanwendung, die Teil der Entwicklertools ist, die Sie von NuGet herunterladen können. Informationen zum Herunterladen dieser Tools finden Sie unter Dataverse-Entwicklungstools.

Verbinden mit dem Plugin-Registrierungstool

  1. Öffnen Sie das Plug-In-Registrierungstool, indem Sie den PAC CLI-Befehl pac tool prt ausführen.

  2. Wählen Sie +Neue Verbindung erstellen, um eine Verbindung mit Ihrer Dataverse-Umgebung herzustellen.

  3. Stellen Sie sicher, dass Office 365 aktiviert ist.

  4. Wenn Sie eine Verbindung mit einem anderen Microsoft-Konto als einem konto herstellen, das Sie derzeit verwenden, wählen Sie "Erweitert anzeigen" aus, und geben Sie Ihre Anmeldeinformationen ein. Lassen Sie andernfalls "Anmelden als aktueller Benutzer" ausgewählt.

    Hinweis

    Wenn Ihr Benutzerkonto die mehrstufige Authentifizierung (MFA) verwendet, stellen Sie sicher, dass das Kontrollkästchen "Erweitert anzeigen " nicht aktiviert ist.

  5. Wenn Ihr Microsoft-Konto Zugriff auf mehrere Umgebungen bietet, wählen Sie "Liste der verfügbaren Organisationen anzeigen" aus.

    Melden Sie sich mit dem Plug-In-Registrierungstool an.

  6. Wählen Sie Anmelden aus.

  7. Wenn Sie die Liste der verfügbaren Organisationen anzeigen ausgewählt haben, wählen Sie die Organisation aus, mit der Sie eine Verbindung herstellen möchten, und wählen Sie "Anmelden" aus.

  8. Nachdem Sie eine Verbindung hergestellt haben, werden alle vorhandenen registrierten Plug-Ins, benutzerdefinierte Workflowaktivitäten und Datenanbieter angezeigt.

    Zeigen Sie vorhandene Plug-Ins und benutzerdefinierte Workflowaktivitäten an.

Erstellen einer benutzerdefinierten API

Wählen Sie im Menü "Registrieren" den Befehl "Neue benutzerdefinierte API registrieren " aus. Diese Aktion öffnet das Formular, um eine benutzerdefinierte API zu erstellen.

Screenshot des Formulars zum Erstellen einer benutzerdefinierten API im Plug-In-Registrierungstool.

Verwenden Sie die folgende Tabelle, um die Custom API zu erstellen. Weitere Informationen finden Sie in den Spalten der benutzerdefinierten API-Tabelle.

Wichtig

Einige Optionen können nicht geändert werden, nachdem Sie die benutzerdefinierte API gespeichert haben. Stellen Sie sicher, dass Sie den Zweck jeder Einstellung verstehen, die nicht geändert werden kann. Wenn Sie diese Einstellung später ändern müssen, müssen Sie die benutzerdefinierte API löschen und erneut erstellen. Diese Aktion löscht auch alle Anforderungsparameter oder Antworteigenschaften, die ihr zugeordnet sind.

Beschriftung Beschreibung Kann geändert werden
Anzeigename Ein lokalisierbarer Name. Ja
Name Ein freundlicher, nicht lokalisierbarer Name. Ja
Lösung Erstellen Sie eine neue Lösung, oder wählen Sie eine vorhandene Lösung aus. Durch Festlegen dieses Werts wird das entsprechende Anpassungspräfix für das Feld " Eindeutiger Name " festgelegt. Ja
Eindeutiger Name Der Name der benutzerdefinierten API. Dieser Wert darf nur alphanumerische Zeichen und keine Leerzeichen enthalten.
Der vollständige Name enthält das Anpassungspräfix, das durch Auswählen der Lösung bestimmt wird.		 Nr.
Beschreibung Eine lokalisierbare Beschreibung. Wird verwendet, wenn die Nachricht zum Aufruf in einer App freigegeben wird. Beispielsweise als QuickInfo. Ja
Montage Optional. Wählen Sie eine Assembly aus, die einen Plug-In-Typ enthält, der definiert, was die benutzerdefinierte API tut. Ja
Plug-In Optional. Wählen Sie einen Plug-In-Typ innerhalb der ausgewählten Assembly aus. Sie können diesen Wert später festlegen. Ja
Zulässiger benutzerdefinierter Verarbeitungsschritttyp Welche Arten von Verarbeitungsschritten erlauben Sie? Weitere Informationen: Auswählen eines benutzerdefinierten Verarbeitungsschritttyps Nr.
Bindungstyp Welche Art von Entitätsbindung. Weitere Informationen: Auswählen eines Bindungstyps Nr.
Logischer Name der gebundenen Entität Wenn Sie Binding TypeEntity oder EntityCollection auswählen, geben Sie den logischen Namen der Tabelle ein, die diesen Typ darstellt. Nr.
Name der Ausführungsberechtigung Der Name eines Privilegs, das steuert, ob jemand die API verwenden kann. Dieser Name muss ein gültiger Name-Wert aus der Tabelle "Privilege " sein. Weitere Informationen: Sichern Der benutzerdefinierten API durch Anfordern einer Berechtigung Ja
Funktion Gibt an, ob eine Funktion erstellt werden soll. Weitere Informationen: Wann eine Funktion erstellt werden soll Nr.
Privat Gibt an, ob die benutzerdefinierte API privat sein soll. Weitere Informationen: Wann soll Ihre benutzerdefinierte API privat werden? Ja

Hinweis

  • Der benutzerdefinierte PRT-API-Designer macht die Eigenschaft "Enabled For Workflow (WorkflowSdkStepEnabled)" nicht verfügbar. Wenn Sie eine benutzerdefinierte API erstellen möchten, die für Workflows funktioniert, verwenden Sie eine andere Methode.
  • Der benutzerdefinierte PRT-API-Designer macht die verwaltete Is Customizeable-Eigenschaft nicht verfügbar. Sie können diese Eigenschaft in Power Apps festlegen. Weitere Informationen finden Sie unter Custom API Customization.

Sie können weiterhin Anforderungsparameter und Antworteigenschaften hinzufügen oder die benutzerdefinierte API speichern und später hinzufügen.

Erstellen von benutzerdefinierten API-Anforderungsparametern

Eine benutzerdefinierte API erfordert keine Anforderungsparameter. Beim Erstellen oder Bearbeiten einer benutzerdefinierten API können Sie Anforderungsparameter hinzufügen, indem Sie + Anforderungsparameter hinzufügen auswählen. Mit dieser Auswahl wird das Parameter-Formular geöffnet.

Screenshot des Parameterformulars zum Erstellen eines benutzerdefinierten API-Anforderungsparameters.

Verwenden Sie die folgende Tabelle, um den Anforderungsparameter zu erstellen. Weitere Informationen finden Sie unter CustomAPIRequestParameter Table Columns.

Beschriftung Beschreibung Kann geändert werden
Anzeigename Lokalisierbarer Anzeigename. Ja
Name Der primäre Name des benutzerdefinierten API-Anforderungsparameters. Verwenden Sie diese Benennungskonvention, um diesen Parameter von anderen zu unterscheiden, die einen gemeinsamen eindeutigen Namen verwenden: {Custom API Unique Name}.{Parameter UniqueName} Ja
Eindeutiger Name Der Name des Parameters, wenn Sie die benutzerdefinierte API aufrufen. Nr.
Typ Wählen Sie den Typ des Parameters aus.
Aktiv
Datum/Uhrzeit
Dezimal
Entität
EntityCollection
EntityReference
Gleitkommazahl
Ganzzahl
Geld
Auswahlliste
String
StringArray
Guid
 Nr.
Logischer Entitätsname Wenn Sie Entity, EntityCollection oder EntityReference als Typ auswählen, geben Sie die Tabelle an. Nr.
Beschreibung Lokalisierbare Beschreibung. Ja
Ist optional Gibt an, ob der Aufrufer einen Wert für den Parameter angeben muss. Nr.

Erstellen von benutzerdefinierten API-Antworteigenschaften

Eine benutzerdefinierte API für eine Aktion erfordert keine Antworteigenschaften. Beim Erstellen einer benutzerdefinierten API oder Bearbeiten einer vorhandenen API können Sie neue Antworteigenschaften erstellen, indem Sie + Antwortparameter hinzufügen auswählen. Mit dieser Auswahl wird das Formular „Parameter“ geöffnet.

Screenshot des Parameterformulars zum Erstellen einer benutzerdefinierten API-Antworteigenschaft.

Verwenden Sie die folgende Tabelle, um die Antworteigenschaft zu erstellen. Weitere Informationen finden Sie unter CustomAPIResponseProperty Table Columns.

Beschriftung Beschreibung Kann geändert werden
Anzeigename Lokalisierbarer Anzeigename. Ja
Name Der primäre Name der benutzerdefinierten API-Antworteigenschaft. Verwenden Sie diese Benennungskonvention, um diesen Parameter von anderen zu unterscheiden, die denselben gemeinsamen Unique Name haben: {Custom API Unique Name}.{Property UniqueName} Ja
Eindeutiger Name Dieser Name ist die Eigenschaft, die zurückgegeben wird, wenn Sie die benutzerdefinierte API aufrufen. Nr.
Typ Wählen Sie den Typ der Eigenschaft aus.
Aktiv
Datum/Uhrzeit
Dezimal
Entität
EntityCollection
EntityReference
Gleitkommazahl
Ganzzahl
Geld
Auswahlliste
String
StringArray
Guid
 Nr.
Logischer Entitätsname Wenn Sie Entity oder EntityReference als Typ auswählen, geben Sie die Tabelle an. Sie können keinen logischen Entitätsnamen angeben, wenn Sie "EntityCollection " als Typ auswählen. Nr.
Beschreibung Lokalisierbare Beschreibung. Ja

Anzeigen einer Liste von benutzerdefinierten APIs

Um eine Liste benutzerdefinierter APIs anzuzeigen, wählen Sie im Menü "Ansicht" den Befehl "Nach Meldung anzeigen" aus.

Screenshot des Befehls „Display by Message“ im Menü „Ansicht“ mit benutzerdefinierten APIs.

Alle Nachrichten, die Sie als benutzerdefinierte API erstellt haben, sind mit (Benutzerdefinierte API) gekennzeichnet.

Löschen einer benutzerdefinierten API

Wenn Sie eine Liste benutzerdefinierter APIs anzeigen, wählen Sie die API aus, die Sie löschen möchten, und wählen Sie Abmelden aus.

Screenshot des Befehls „Unregister“, der zum Löschen einer ausgewählten benutzerdefinierten API verwendet wird.

Oder klicken Sie mit der rechten Maustaste auf das Element, und wählen Sie im Kontextmenü die Option " Registrierung aufheben " aus.

Aktualisieren von benutzerdefinierten API-Anforderungsparametern oder Antworteigenschaften

Wählen Sie in der Liste der Anforderungsparameter oder Antworteigenschaften die Spalte aus, die Sie bearbeiten möchten:

Screenshot der Spalte, die zum Bearbeiten eines benutzerdefinierten API-Anforderungsparameters oder einer Antworteigenschaft verwendet wird.

Löschen von benutzerdefinierten API-Anforderungsparametern oder Antworteigenschaften

Wählen Sie in der Liste der Anforderungsparameter oder Antworteigenschaften die Spalte aus, die Sie löschen möchten:

Screenshot der Spalte, die zum Löschen eines benutzerdefinierten API-Anforderungsparameters oder einer Antworteigenschaft verwendet wird.

Nächste Schritte

Wenn Sie die IsPrivate Eigenschaft für Ihre benutzerdefinierte API nicht festlegen, können Sie die Dienstdefinition abrufen, nachdem Sie Ihre benutzerdefinierte API erstellt haben. Verwenden Sie eine GET Anfrage, um das CSDL-$metadata-Dokument auch aus Ihrem Browser abzurufen. Wenn die URL für Ihre Umgebung lautet https://yourorg.crm.dynamics.com, geben Sie diese URL in Ihr Browseradressenfeld ein, um die $metadata abzurufen: https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata.

Durchsuchen Sie das Ergebnis, um den Namen der benutzerdefinierten API zu finden. Sie finden die Aktion oder Funktion zusammen mit einem verwandten ComplexType, um den Rückgabewert darzustellen. Zum Beispiel:

<ComplexType Name="sample_CustomAPIExampleResponse">
    <Property Name="StringProperty"
        Type="Edm.String"
        Unicode="false"/>
</ComplexType>
<Action Name="sample_CustomAPIExample">
    <Parameter Name="StringParameter"
        Type="Edm.String"
        Nullable="false"
        Unicode="false"/>
    <ReturnType Type="mscrm.sample_CustomAPIExampleResponse"
        Nullable="false"/>
</Action>

Auch wenn Sie kein Plug-In für Ihre benutzerdefinierte API festlegen, können Sie es testen, um die Signatur zu überprüfen. Die Antworteigenschaften geben ihre Standardwerte zurück, da es kein Plug-In zum Festlegen der Werte gibt. Weitere Informationen finden Sie unter Aufrufen von benutzerdefinierten APIs.

Wenn Sie ein Plug-In hinzufügen, müssen Sie es schreiben und die Assembly registrieren. Aktualisieren Sie dann Ihre benutzerdefinierte API, um die Assembly und das Plug-In festzulegen, um anzugeben, welcher Code als Reaktion auf Ihre benutzerdefinierte API ausgeführt werden soll. Weitere Informationen finden Sie unter Schreiben eines Plug-Ins für Ihre benutzerdefinierte API.

Siehe auch

Angepasste APIs erstellen und verwenden
Erstellen einer benutzerdefinierten API in Power Apps
Erstellen einer benutzerdefinierten API mit Code
Erstellen einer benutzerdefinierten API mit Lösungsdateien
Erstellen eigener Nachrichten
Spalten für benutzerdefinierte API-Tabellen

  • Zuletzt aktualisiert um