IoT Central REST API gebruiken om gebruikers en rollen te beheren

Artikel
10/22/2024

Met de REST API van IoT Central kunt u clienttoepassingen ontwikkelen die kunnen worden geïntegreerd met IoT Central-toepassingen. U kunt de REST API gebruiken om gebruikers en rollen in uw IoT Central-toepassing te beheren.

Elke IoT Central REST API-aanroep vereist een autorisatieheader. Zie IoT Central REST API-aanroepen verifiëren en autoriseren voor meer informatie.

Notitie

Bewerkingen voor gebruikers en rollen worden vastgelegd in het Auditlogboek van IoT Central.

Zie de naslaginformatie voor de REST API van IoT Central voor Azure IoT Central.

Zie Gebruikers en rollen beheren in uw IoT Central-toepassing voor meer informatie over het beheren van gebruikers en rollen met behulp van de gebruikersinterface van IoT Central.

Rollen beheren

Met de REST API kunt u de rollen weergeven die zijn gedefinieerd in uw IoT Central-toepassing. Gebruik de volgende aanvraag om een lijst met rol-id's op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld met de drie ingebouwde rollen en een aangepaste rol:

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

Notitie

Met deze opdracht worden alleen rollen weergegeven die zijn gekoppeld aan een toepassing en geen aangepaste rol op organisatieniveau.

Gebruikers beheren

Met de REST API kunt u het volgende doen:

De gebruikers in een toepassing vermelden
De details van een afzonderlijke gebruiker ophalen
Een gebruiker maken
Een gebruiker wijzigen
Een gebruiker verwijderen

Gebruikers weergeven

Gebruik de volgende aanvraag om een lijst met gebruikers op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De rolwaarden identificeren de rol-id waarmee de gebruiker is gekoppeld:

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

Een gebruiker ophalen

Gebruik de volgende aanvraag om details van een afzonderlijke gebruiker op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De rolwaarde identificeert de rol-id waaraan de gebruiker is gekoppeld:

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

Een gebruiker maken

Gebruik de volgende aanvraag om een gebruiker in uw toepassing te maken. De id en het e-mailadres moeten uniek zijn in de toepassing:

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

In de volgende aanvraagbody is de role waarde voor de operatorrol die u eerder hebt opgehaald:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De rolwaarde bepaalt aan welke rol de gebruiker is gekoppeld:

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

U kunt ook een service-principalgebruiker toevoegen die handig is als u verificatie van de service-principal moet gebruiken voor REST API-aanroepen. Zie Een service-principalgebruiker toevoegen of bijwerken voor meer informatie.

De rol van een gebruiker wijzigen

Gebruik de volgende aanvraag om de rol te wijzigen die aan de gebruiker is toegewezen. In dit voorbeeld wordt de id gebruikt van de opbouwfunctie die u eerder hebt opgehaald:

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

Aanvraagtekst. De waarde is voor de opbouwfunctie die u eerder hebt opgehaald:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een gebruiker verwijderen

Gebruik de volgende aanvraag om een gebruiker te verwijderen:

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

Volgende stappen

Nu u hebt geleerd hoe u gebruikers en rollen beheert met de REST API, is een voorgestelde volgende stap het gebruik van de IoT Central REST API voor het beheren van organisaties.

Share via