Comment utiliser l’API REST IoT Central pour gérer les utilisateurs et les rôles

Article
06/13/2023

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent à des applications IoT Central. Vous pouvez utiliser l’API REST pour gérer les utilisateurs et les rôles dans votre application IoT Central.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation. Pour plus d’informations, consultez Comment authentifier et autoriser les appels d’API REST d’IoT Central.

Remarque

Les opérations sur les utilisateurs et les rôles sont enregistrées dans le journal d’audit IoT Central.

Pour obtenir la documentation de référence sur l’API REST IoT Central, consultez Informations de référence sur l’API REST d’Azure IoT Central.

Conseil

Vous pouvez utiliser Postman pour tester les appels d’API REST décrits dans cet article. Téléchargez la collection IoT Central Postman et importez-la dans Postman. Dans la collection, vous devez définir des variables telles que votre sous-domaine d’application et le jeton d’administrateur.

Pour savoir comment gérer les utilisateurs et les rôles à l’aide de l’interface utilisateur IoT Central, consultez Gérer les utilisateurs et les rôles dans votre application IoT Central.

Gérer les rôles

L’API REST vous permet de répertorier les rôles définis dans votre application IoT Central. Utilisez la requête suivante pour récupérer une liste d’ID de rôle à partir de votre application :

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

La réponse à cette demande ressemble à l’exemple suivant, qui comprend les trois rôles intégrés et un rôle personnalisé :

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

Remarque

Cette commande affiche uniquement les rôles associés à une application et non pas un rôle de niveau organisation personnalisé.

Gérer les utilisateurs

L’API REST vous permet de :

Répertorier les utilisateurs dans une application
Récupérer les détails d’un utilisateur individuel
Créer un utilisateur
Modifier un utilisateur
Supprimer un utilisateur

Répertorier les utilisateurs

Utilisez la requête suivante pour récupérer une liste d’utilisateurs à partir de votre application :

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

La réponse à cette demande se présente comme dans l’exemple suivant. Les valeurs de rôle identifient l’ID de rôle auquel l’utilisateur est associé :

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

Obtenir un utilisateur

Utilisez la requête suivante pour récupérer les détails d’un utilisateur individuel à partir de votre application :

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

La réponse à cette demande se présente comme dans l’exemple suivant. La valeur de rôle identifie l’ID de rôle auquel l’utilisateur est associé :

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

Créer un utilisateur

Utilisez la requête suivante pour créer un utilisateur dans votre application. L’ID et l’e-mail doivent être uniques dans l’application :

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

Dans le corps de la requête suivante, la valeur role est pour le rôle d’opérateur que vous avez récupéré précédemment :

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

La réponse à cette demande se présente comme dans l’exemple suivant. La valeur de rôle identifie le rôle auquel l’utilisateur est associé :

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

Vous pouvez également ajouter un utilisateur de principal de service, qui est utile si vous devez utiliser l’authentification du principal du service pour les appels de l’API REST. Pour en savoir plus, consultez Ajouter ou mettre à jour un utilisateur de principal de service.

Modifier le rôle d’un utilisateur

Utilisez la demande suivante pour modifier le rôle attribué à l’utilisateur. Cet exemple utilise l’ID du rôle Générateur que vous avez récupéré précédemment :

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

Corps de la demande. La valeur est pour le rôle Générateur que vous avez récupéré précédemment :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Supprimer un utilisateur

Pour supprimer un utilisateur, utilisez la requête suivante :

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

Étapes suivantes

Maintenant que vous savez comment gérer les utilisateurs et les rôles dans l’API REST, nous vous suggérons d’apprendre à utiliser l’API REST IoT Central pour gérer des organisations.

Share via