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

Artikel
2024-10-22

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.

Anteckning

Åtgärder för användare och roller registreras i IoT Central-granskningsloggen.

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

Anteckning

Det här kommandot visar bara roller som är associerade med ett program och inte en anpassad roll på organisationsnivå.

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.

Dela via