Uso de la API REST de IoT Central para administrar usuarios y roles

  • Artículo

La API de REST de IoT Central permite desarrollar aplicaciones cliente que se integran con aplicaciones de IoT Central. Puede usar la API REST para administrar usuarios y roles en su aplicación de IoT Central.

Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.

Nota:

Las operaciones en usuarios y roles se registran en el registro de auditoría de IoT Central.

Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.

Sugerencia

Puede usar Postman para probar las llamadas API REST que se describen en este artículo. Descargue la colección de Postman de IoT Central e impórtela en Postman. En la colección, deberá establecer variables como el subdominio de la aplicación y el token de administrador.

Para obtener más información sobre cómo administrar usuarios y roles mediante la interfaz de usuario de IoT Central, consulte Administrar usuarios y roles en la aplicación de IoT Central.

Administrar roles

La API REST permite enumerar los roles definidos en su aplicación de IoT Central. Use la siguiente solicitud para recuperar una lista de identificadores de rol de la aplicación:

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

La respuesta a esta solicitud es similar al ejemplo siguiente, que incluye los tres roles integrados y un rol personalizado:

{
  "value": [
    {
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
      "displayName": "Administrator"
    },
    {
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
      "displayName": "Operator"
    },
    {
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
      "displayName": "Builder"
    },
    {
      "id": "16f8533f-6b82-478f-8ba8-7e676b541b1b",
      "displayName": "Example custom role"
    }
  ]
}

Nota:

Este comando solo muestra roles asociados con una aplicación y no un rol personalizado a nivel de organización.

Administrar usuarios

La API de REST permite:

  • Enumerar los usuarios de una aplicación.
  • Recuperar los detalles de un usuario individual.
  • Creación de un usuario
  • Modificar un usuario.
  • Eliminación de usuarios

Enumerar usuarios

Use la siguiente solicitud para recuperar una lista de usuarios de la aplicación:

GET https://{your app subdomain}.azureiotcentral.com/api/users?api-version=2022-07-31

La respuesta a esta solicitud es similar al ejemplo siguiente. Los valores de rol identifican el identificador de rol al que está asociado el usuario:

{
  "value": [
    {
      "id": "91907508-04fe-4349-91b5-b872f3055a95",
      "type": "email",
      "roles": [
        {
          "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
        }
      ],
      "email": "user1@contoso.com"
    },
    {
      "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
      "type": "email",
      "roles": [
        {
          "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
        }
      ],
      "email": "user2@contoso.com"
    },
    {
      "id": "3ab9375e-d2d9-42da-b419-6ae86a938321",
      "type": "email",
      "roles": [
        {
          "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
        }
      ],
      "email": "user3@contoso.com"
    },
    {
      "id": "fc5a250b-83fb-433d-892c-e0a144f68c2b",
      "type": "email",
      "roles": [
        {
          "role": "16f8533f-6b82-478f-8ba8-7e676b541b1b"
        }
      ],
      "email": "user4@contoso.com"
    }
  ]
}

Obtener un usuario

Use la siguiente solicitud para recuperar los detalles de un usuario individual desde la aplicación:

GET https://{your app subdomain}.azureiotcentral.com/api/users/dc1c916b-a652-49ea-b128-7c465a54c759?api-version=2022-07-31

La respuesta a esta solicitud es similar al ejemplo siguiente. El valor de rol indica el identificador de rol al que está asociado el usuario:

{
  "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user2@contoso.com"
}

Creación de un usuario

Use la siguiente solicitud para crear un usuario en la aplicación. El identificador y el correo electrónico deben ser únicos en la aplicación:

PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

En el siguiente cuerpo de la solicitud, el valor role es para el rol de operador que recuperó anteriormente:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

La respuesta a esta solicitud es similar al ejemplo siguiente. El valor de rol indica el rol al que está asociado el usuario:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

También puede agregar un usuario de entidad de servicio que sea útil si necesita utilizar la autenticación de entidad de servicio para llamadas de API de REST. Para más información, consulte Incorporación o actualización de un usuario de entidad de servicio.

Cambio del rol de un usuario

Use la siguiente solicitud para cambiar el rol asignado al usuario. En este ejemplo se usa el identificador del rol de generador que recuperó anteriormente:

PATCH https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

Cuerpo de la solicitud. El valor es para el rol de generador que recuperó anteriormente:

{
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ],
  "email": "user5@contoso.com"
}

Eliminación de usuarios

Use la siguiente solicitud para eliminar un usuario:

DELETE https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

Pasos siguientes

Ahora que ha aprendido a administrar usuarios y roles con la API REST, el siguiente paso que se sugiere es Uso de la API REST de IoT Central para administrar las organizaciones.