Beispiel: IsSystemAdmin Custom-API

Artikel
09/29/2023

Dieses Beispiel zeigt, wie ein Plug-In geschrieben wird, das eine benutzerdefinierte API mit dem Namen sample_IsSystemAdmin unterstützt.

SDK für .NET: Beispielcode für die benutzerdefinierte IsSystemAdmin-API

Dieses Beispiel erstellt ein Plug-In für den Hauptvorgang der Custom-API von sample_IsSystemAdmin. Diese Custom-API erkennt, ob ein Benutzer die Sicherheitsrolle Systemadministrator hat.

Um festzustellen, ob ein Benutzer das System Administrator Sicherheitsrolle hat, sind möglicherweise zwei separate Abfragen erforderlich, je nachdem, ob dem Benutzer Sicherheitsrolle direkt zugewiesen wurde oder ob er es aufgrund des Teams hat, zu dem er gehört. Diese Custom-API kapselt diese Abfragen in einen einzigen API-Aufruf, der einen booleschen Wert zurückgibt. Dies erleichtert die Verwendung, indem der Vorgang an die delegiert wird Dataverse Server.

Wie man dieses Beispiel ausführt

Um den in diesem Beispiel gefundenen Code auszuführen, müssen Sie zunächst eine benutzerdefinierte API in Ihrer Organisation erstellen. Es gibt zwei Möglichkeiten, dies zu tun.

Importieren der verwalteten Lösungsdatei

Die IsSystemAdminFunction_1_0_0_0_managed.zip in diesem Ordner enthält die sample_IsSystemAdmin Custom-API, die diesen Code verwendet. Sie können diese Lösungsdatei einfach importieren, um die Custom-API in Ihrem Unternehmen zu erstellen. Siehe Lösungen importieren für Anweisungen.

Nachdem Sie die Tests abgeschlossen haben, löschen Sie die verwaltete Lösung, um die Custom-API zu entfernen.

Erstellen der Custom-API

Sie können die Custom-API selbst erstellen und die von diesem Code erstellte Plugin-Assembly einstellen. Es gibt mehrere Möglichkeiten, eine Custom-API zu erstellen, und sie sind hier dokumentiert: Custom-APIs erstellen und verwenden

Diese Custom-API ist mit den folgenden Daten definiert:

{
  "uniquename": "sample_IsSystemAdmin",
  "allowedcustomprocessingsteptype": 0,
  "bindingtype": 1,
  "boundentitylogicalname": "systemuser",
  "description": "Returns whether the user has the System Administrator security role",
  "name": "Is System Administrator",
  "displayname": "Is System Administrator",
  "executeprivilegename": null,
  "isfunction": true,
  "isprivate": false,
  "workflowsdkstepenabled": false,
  "iscustomizable": {
    "Value": false
  },
  "CustomAPIResponseProperties": [
    {
      "uniquename": "HasRole",
      "name": "Has Role",
      "description": "Whether the user has the System Administrator security role",
      "displayname": "Has Role",
      "type": 0,
      "logicalentityname": null,
      "iscustomizable": {
        "Value": false
      }
    }
  ]
}

Sie können diese Daten verwenden, um die benutzerdefinierte API mit Insomnia und der Web-API zu erstellen, indem Sie dem Beispiel hier folgen: Eine benutzerdefinierte API mit Code erstellen.

Informationen zu den übergebenen Werten finden Sie in diesen Themen: CustomAPI-Tabellen

Diese Custom-API ist eine Funktion, die an die Tabelle Benutzer (SystemUser) gebunden ist. Es hat eine einzelne boolesche Antworteigenschaft HasRole die zurückkehren wird true wenn der Benutzer das System Administrator Sicherheitsrolle. hat

Nachdem Sie die Custom-API wie oben definiert erstellt haben, erstellen Sie dieses .NET Class Library Projekt, um eine Plug-in Assembly mit dem Namen IsSystemAdminCustomAPI.dll zu generieren. Diese Assembly hat einen einzelnen Plug-In-Typ namens PowerApps.Samples.IsSystemAdmin.

Sie müssen die erstellte Plug-In-Assembly mit dem Plug-In-Registrierungstool wie hier beschrieben registrieren: Plugin registrieren

Nachdem das Plug-in registriert ist, können Sie es als Typ für die Custom-API festlegen.

Die von Ihnen erstellte sample_IsSystemAdmin-Custom-API wird Teil der nicht verwalteten Anpassungen in Ihrer Umgebung sein. Um es zu entfernen, müssen Sie die Custom-API und die Plugin-Assembly löschen.

Funktionsweise

Diese sample_IsSystemAdmin Custom-API verwendet diesen Code, um das System abzufragen, ob der Benutzer die Sicherheitsrolle Systemadministrator hat.

Wie dieses Beispiel funktioniert

Um die benutzerdefinierte API sample_IsSystemAdmin zu verwenden, können Sie entweder die Web-API oder die .NET Framework SDK-Assemblys von Dataverse verwenden.

Verwenden von Web-API

Die Web-API ist am einfachsten auszuprobieren, da Sie keinen Code schreiben müssen. Sie können es mit Ihrem Browser testen.

Rufen Sie die Web-API-URL von der Seite „Entwicklerressourcen“ ab. Siehe Entwicklerressourcen anzeigen. Der Wert wird ungefähr so aussehen: https://yourorgname.api.crm.dynamics.com/api/data/v9.2.
Kopieren Sie diese Web-API-URL, und fügen Sie sie in die Adressleiste eines Browsers ein. Sie werden möglicherweise zur Authentifizierung aufgefordert, wenn Sie zuvor noch keine modellgesteuerte Anwendung ausgeführt haben.
Bearbeiten Sie die Web-API-URL, um Informationen zu Systembenutzern zurückzugeben. Fügen Sie Folgendes an die Web-API-URL an: /systemusers?$select=fullname. Sie sollten JSON-Daten in Ihrem Browser sehen können.
Wählen Sie einen der systemuserid Werte für einen Benutzer und öffnen Sie einen anderen Browser-Tab.
Erstellen Sie in diesem Browser-Tab die folgende URL mit Ihrer Web-API-URL und der systemuserid Wert:
https://<your org url>/api/data/v9.2/systemusers(<The systemuserid value>)/Microsoft.Dynamics.CRM.sample_IsSystemAdmin
Sie müssen den Microsoft.Dynamics.CRM-Namespace einschließen, da dies eine gebundene Funktion ist. Weitere Informationen: Gebundene Funktionen
Sie sollten Ergebnisse wie die folgenden sehen, wenn Sie die Anfrage senden:

{
  "@odata.context": "https://yourorgname.api.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.sample_IsSystemAdminResponse",
  "HasRole": false
}

Der HasRole-Wert gibt an, ob der Benutzer über die Sicherheitsrolle Systemadministrator verfügt.

Verwenden des SDK für .NET

Sie können die Beispielanweisungen für den SDK für .NET-Schnellstart verwenden, um eine .NET Framework-Konsolenanwendung mit C# zu erstellen. Schnellstart: SDK für .NET-Beispiel (C#)

Fügen Sie die folgende statische Methode zur Programmklasse hinzu. Dadurch wird eine wiederverwertbare Methode erstellt.

static bool IsSystemAdmin(IOrganizationService svc, Guid systemuserid)
{

    var req = new OrganizationRequest("sample_IsSystemAdmin")
    {
        ["Target"] = new EntityReference("systemuser", systemuserid)
    };

    var resp = svc.Execute(req);

    var hasRole = (bool)resp["HasRole"];

    return hasRole;
}

Ersetzen Sie den Code namens WhoAmIRequest durch den folgenden:

 //Compose a query to retrieve top 10 users
QueryExpression query = new QueryExpression("systemuser");
query.ColumnSet = new ColumnSet("fullname");
query.TopCount = 10;

 //Execute the query to retrieve the data
EntityCollection users = svc.RetrieveMultiple(query);

foreach (Entity user in users.Entities)
{
     //Test each record returned using  the custom API
    bool isAdmin = IsSystemAdmin(svc, user.Id);

     //Show the results in the console
    Console.WriteLine($"{user["fullname"]} is{(isAdmin? string.Empty: " not")} an administrator");
}

Dieser Code ruft 10 Benutzer ab und durchläuft jeden einzelnen, testet, ob es sich um ein System Administrator handelt oder nicht, und schreibt die Ergebnisse in die Konsole.

Demonstrieren

Abfrage, ob der Benutzer ein System ist Administrator
Wie Sie ein Plug-In zur Unterstützung einer benutzerdefinierten API schreiben
Wie ruft man eine Custom-API-Funktion über die Web-API auf?
So rufen Sie eine benutzerdefinierte API mithilfe des SDK für .NET auf

Siehe auch

Benutzerdefinierte APIs erstellen und verwenden
Schreiben eines Plug-Ins
Registrieren eines Plug-Ins

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).