Exemple : API personnalisée IsSystemAdmin

Article
09/21/2023

Cet exemple montre comment écrire un plug-in qui prend en charge une API personnalisée nommée sample_IsSystemAdmin.

Kit de développement logiciel (SDK) pour .NET : exemple de code d’API personnalisée IsSystemAdmin

Cet exemple crée un plug-in pour l’opération principale de l’API personnalisée sample_IsSystemAdmin. Cette API personnalisée détectera si un utilisateur a le rôle de sécurité administrateur système.

Détecter si un utilisateur a le rôle de sécurité administrateur système peut nécessiter deux requêtes distinctes selon que l’utilisateur s’est vu attribuer le rôle de sécurité directement ou s’il l’a en raison de l’équipe à laquelle il appartient. Cette API personnalisée encapsule ces requêtes dans un seul appel d’API qui renverra une valeur booléenne. Cela facilite son utilisation en déléguant l’exploitation au serveur Dataverse.

Comment exécuter cet exemple

Pour exécuter le code trouvé dans cet exemple, vous devez d’abord créer une API personnalisée dans votre organisation. Deux méthodes s’offrent à vous pour ce faire.

Importer le fichier de solution gérée

Le fichier IsSystemAdminFunction_1_0_0_0_managed.zip dans ce dossier contient l’API personnalisée sample_IsSystemAdmin qui utilise ce code. Vous pouvez simplement importer ce fichier de solution pour créer l’API personnalisée dans votre organisation. Voir Importer des solutions pour les consignes.

Une fois les tests terminés, supprimez le solution gérée pour supprimer l’API personnalisée.

Créer l’API personnalisée

Vous pouvez créer vous-même l’API personnalisée et définir l’assembly de plug-in créé par ce code. Il existe plusieurs façons de créer une API personnalisée, et elles sont documentées ici : Créer et utiliser des API personnalisées

Cette API personnalisée est définie avec les données suivantes :

{
  "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
      }
    }
  ]
}

Vous pouvez utiliser ces données pour créer l’API personnalisée à l’aide de Insomnia et l’API web en suivant l’exemple ici : Créer une API personnalisée avec du code.

Pour plus d’informations sur les valeurs transmises, consultez ces rubriques : Tables CustomAPI

Cette API personnalisée est une fonction liée au Tableau Utilisateur (SystemUser). Il a une seule propriété de réponse booléenne HasRole qui renverra true lorsque l’utilisateur a le rôle de sécurité administrateur système.

Après avoir créé l’API personnalisée comme défini ci-dessus, créez ce projet de bibliothèque de classes .NET pour générer un assembly de plug-in nommé IsSystemAdminCustomAPI.dll. Cet assembly aura un seul type de plug-in nommé PowerApps.Samples.IsSystemAdmin.

Vous devez enregistrer l’assembly de plug-in créé à l’aide de l’outil d’enregistrement de plug-in comme décrit ici : Enregistrer le plug-in

Une fois le plug-in enregistré, vous pourrez le définir comme type de plug-in pour l’API personnalisée.

L’API personnalisée sample_IsSystemAdmin que vous créez fera partie des personnalisations non gérées dans votre environnement. Pour le supprimer, vous devez supprimer l’API personnalisée et l’assemblage de plug-in.

En quoi consiste cet exemple

Cette API personnalisée sample_IsSystemAdmin utilise ce code pour interroger le système afin de détecter si l’utilisateur dispose du rôle de sécurité administrateur système.

Utiliser cet exemple

Pour utiliser l’API personnalisée sample_IsSystemAdmin, vous pouvez utiliser l’API web ou les assemblys du Kit de développement logiciel (SDK) .NET Framework Dataverse.

Utilisation de l’API Web

L’API Web est la plus facile à essayer car vous n’avez pas besoin d’écrire de code. Vous pouvez la tester avec votre navigateur.

Obtenez l’URL de l’API Web à partir de la page Ressources pour les développeurs. Voir Afficher les ressources du développeur. La valeur ressemblera à ce qui suit : https://yourorgname.api.crm.dynamics.com/api/data/v9.2.
Copiez l’URL de l’API web et collez-la dans la barre d’adresse d’un navigateur. Vous pouvez être invité à vous authentifier si vous n’avez jamais exécuté d’application pilotée par modèle auparavant.
Modifiez l’URL de l’API Web pour renvoyer des informations sur les utilisateurs système. Ajoutez ce qui suit à l’URL de l’API Web : /systemusers?$select=fullname. Vous devriez pouvoir voir les données JSON dans votre navigateur.
Sélectionnez l’une des valeurs systemuserid pour un utilisateur et ouvrez un autre onglet de navigateur.
Dans cet onglet de navigateur, composez l’URL suivante à l’aide de l’URL de votre API Web et de la valeur systemuserid :
https://<your org url>/api/data/v9.2/systemusers(<The systemuserid value>)/Microsoft.Dynamics.CRM.sample_IsSystemAdmin
Vous devez inclure l’espace de nom Microsoft.Dynamics.CRM car il s’agit d’une fonction liée. Pour plus d’informations : Fonctions liées
Vous devriez voir des résultats comme ceux-ci lorsque vous envoyez la demande :

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

La valeur HasRole indique si l’utilisateur est doté du rôle de sécurité Administrateur système.

Utilisation du SDK pour .NET

Vous pouvez utiliser les exemples Démarrage rapide du SDK pour .NET pour créer une application console .NET Framework avec C#. Démarrage rapide : exemple de SDK pour .NET (C#)

Ajoutez la méthode statique suivante sous la classe du programme. Cela crée une méthode réutilisable.

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

Remplacez le code qui appelle WhoAmIRequest par le suivant :

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

Ce code récupérera 10 utilisateurs et parcourra chacun d’eux, en testant s’il s’agit d’un administrateur système ou non, en écrivant les résultats sur la console.

Démontrer

Comment interroger pour détecter si l’utilisateur est un administrateur système
Comment écrire un plug-in pour prendre en charge une API personnalisée
Comment appeler une fonction d’API personnalisée à l’aide de l’API Web
Comment appeler une fonction d’API personnalisée à l’aide du SDK pour .NET

Voir aussi

Créer et utiliser des API personnalisées
Écrire un plug-in
Enregistrer un plug-in

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Partager via