Ejemplo: API personalizada IsSystemAdmin

Artículo
09/29/2023

Este ejemplo muestra cómo escribir un complemento que admita una API personalizada denominada sample_IsSystemAdmin.

SDK para .NET: código de muestra de la API personalizada de IsSystemAdmin

Este ejemplo crea un complemento para la operación principal de la API personalizada sample_IsSystemAdmin. Esta API personalizada detectará si un usuario tiene el rol de seguridad del administrador del sistema.

Detectar si un usuario tiene el rol de seguridad de administrador del sistema puede requerir dos consultas separadas dependiendo de si al usuario se le ha asignado el rol de seguridad directamente o si lo tiene debido al equipo al que pertenece. Esta API personalizada encapsula estas consultas en una única llamada de API que devolverá un valor booleano. Esto facilita su uso al delegar la operación al servidor Dataverse.

Cómo ejecutar esta muestra

Para ejecutar el código que se encuentra en este ejemplo, primero debe crear una API personalizada en su organización. Esto se puede hacer de dos maneras.

Importar el archivo de solución administrada

El IsSystemAdminFunction_1_0_0_0_managed.zip de esta carpeta contiene la API personalizada sample_IsSystemAdmin que utiliza este código. Simplemente puede importar este archivo de solución para crear la API personalizada en su organización. Consulte Soluciones de importación para obtener instrucciones.

Una vez que haya terminado de probar, elimine la solución administrada para eliminar la API personalizada.

Crear la API personalizada

Puede crear la API personalizada usted mismo y configurar el ensamblado del complemento creado por este código. Hay varias formas de crear una API personalizada y están documentadas aquí: Crear y usar API personalizadas

Esta API personalizada se define con los siguientes datos:

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

Puede usar estos datos para crear la API personalizada usando Insomnia y la API web siguiendo el ejemplo de aquí: Crear una API personalizada con código.

Para obtener información sobre los valores pasados, consulte estos temas: Tablas CustomAPI

Esta API personalizada es una función vinculada a la Tabla de usuario (SystemUser). Tiene una única propiedad de respuesta booleana, HasRole, que devolverá true si el usuario tiene el rol de seguridad de administrador del sistema.

Después de crear la API personalizada como se definió anteriormente, cree este proyecto de biblioteca de clases .NET para generar un ensamblado de complemento llamado IsSystemAdminCustomAPI.dll. Este ensamblado tendrá un solo tipo de complemento llamado PowerApps.Samples.IsSystemAdmin.

Debe registrar el ensamblado del complemento creado mediante la herramienta de registro de complementos como se describe aquí: Registrar complemento

Después de registrar el complemento, podrá configurarlo como tipo de complemento para la API personalizada.

La API personalizada sample_IsSystemAdmin que cree formará parte de las personalizaciones no administradas de su entorno. Para eliminarla, debe eliminar la API personalizada y el ensamblado del complemento.

Qué hace este ejemplo

Esta API personalizada sample_IsSystemAdmin usa este código para consultar el sistema para detectar si el usuario tiene el rol de seguridad de administrador del sistema.

Cómo funciona este ejemplo

Para usar la API personalizada sample_IsSystemAdmin, puede usar la API web o los ensamblados SDK de .NET Framework de Dataverse.

Uso de la API web

La API web es la más fácil de probar porque no necesita escribir ningún código. Puede probarla usando el navegador.

Obtenga la URL de la API web de la página Recursos para desarrolladores. Consulte Ver recursos de desarrollador. El valor será algo similar a esto: https://yourorgname.api.crm.dynamics.com/api/data/v9.2.
Copie la URL de la API web y péguela en la barra de dirección del explorador. Es posible que se le solicite que se autentique si no ha ejecutado previamente una aplicación basada en modelo.
Edite la URL de la API web para devolver información sobre los usuarios del sistema. Anexe lo siguiente a la URL de la API web: /systemusers?$select=fullname. Debería poder ver los datos JSON en el navegador.
Seleccione uno de los valores de systemuserid para un usuario y abra una pestaña diferente del navegador.
En esta pestaña del navegador, redacte la siguiente URL utilizando su URL de API web y el valor systemuserid:
https://<your org url>/api/data/v9.2/systemusers(<The systemuserid value>)/Microsoft.Dynamics.CRM.sample_IsSystemAdmin
Debe incluir el espacio de nombres Microsoft.Dynamics.CRM porque esta es una función enlazada. Más información: Funciones de enlace
Debería ver resultados como los siguientes cuando envíe la solicitud:

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

El valor HasRole indica si el usuario tiene el rol de seguridad de administrador del sistema.

Usar SDK para .NET

Puede usar las instrucciones de ejemplo de inicio rápido del SDK para .NET para crear una aplicación de consola de .NET Framework con C#. Inicio rápido: Ejemplo de SDK para .NET (C#)

Agregue el siguiente método estático a la clase de programa. Esto crea un método que puede reutilizarse.

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

Reemplace el código que llama WhoAmIRequest con lo siguiente:

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

Este código recuperará 10 usuarios y recorrerá cada uno, probando si son un administrador del sistema o no, y escribiendo los resultados en la consola.

Demostración

Cómo consultar para detectar si el usuario es un administrador del sistema
Cómo escribir un complemento para admitir una API personalizada
Cómo invocar una función de API personalizada utilizando la API web
Cómo invocar una función de API personalizada utilizando SDK para .NET

Consulte también

Crear y usar API personalizadas
Escribir un complemento
Registro de un complemento

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Share via