Använda IoT Central REST API till att hantera användare och roller

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Du kan använda REST API för att hantera användare och roller i ditt IoT Central-program.

Varje IoT Central REST API-anrop kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera IoT Central REST API-anrop.

Referensdokumentationen för REST API:et för IoT Central finns i Referens för Rest API för Azure IoT Central.

Information om hur du hanterar användare och roller med hjälp av IoT Central-användargränssnittet finns i Hantera användare och roller i ditt IoT Central-program.

Hantera roller

Med REST-API:et kan du visa en lista över de roller som definierats i ditt IoT Central-program. Använd följande begäran för att hämta en lista över roll-ID:t från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel som innehåller de tre inbyggda rollerna och en anpassad roll:

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

Hantera användare

Med REST-API:et kan du:

• Visa en lista över användare i ett program
• Hämta information om en enskild användare
• Skapa en användare
• Ändra en användare
• Ta bort en användare

Visa användare

Använd följande begäran för att hämta en lista över användare från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel. Rollvärdena identifierar det roll-ID som användaren är associerad med:

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

Hämta en användare

Använd följande begäran för att hämta information om en enskild användare från ditt program:

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

Svaret på den här begäran ser ut som i följande exempel. Rollvärdet identifierar det roll-ID som användaren är associerad med:

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

Skapa en användare

Använd följande begäran för att skapa en användare i ditt program. ID:t och e-postmeddelandet måste vara unika i programmet:

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

I följande begärandetext role är värdet för den operatorroll som du hämtade tidigare:

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

Svaret på den här begäran ser ut som i följande exempel. Rollvärdet identifierar vilken roll användaren är associerad med:

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

Du kan också lägga till en användare av tjänstens huvudnamn som är användbar om du behöver använda autentisering med tjänstens huvudnamn för REST API-anrop. Mer information finns i Lägga till eller uppdatera en användare av tjänstens huvudnamn.

Ändra rollen för en användare

Använd följande begäran för att ändra rollen som tilldelats användaren. I det här exemplet används ID:t för den builder-roll som du hämtade tidigare:

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

Begärandetext. Värdet är för den builder-roll som du hämtade tidigare:

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

Svaret på den här begäran ser ut som i följande exempel:

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

Ta bort en användare

Använd följande begäran för att ta bort en användare:

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

Nästa steg

Nu när du har lärt dig hur du hanterar användare och roller med REST-API:et är ett föreslaget nästa steg att använda REST-API:et i IoT Central för att hantera organisationer.