IoT Central REST API gebruiken om gebruikers en rollen te beheren
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.
Tip
U kunt Postman gebruiken om de REST API-aanroepen uit te proberen die in dit artikel worden beschreven. Download de IoT Central Postman-verzameling en importeer deze in Postman. In de verzameling moet u variabelen instellen, zoals uw app-subdomein en het beheertoken.
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.