Come usare l'API REST IoT Central per gestire utenti e ruoli

Articolo
02/08/2024

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per gestire utenti e ruoli nell'applicazione IoT Central.

Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST di IoT Central.

Nota

Le operazioni su utenti e ruoli vengono registrate nel log di controllo di IoT Central.

Per la documentazione di riferimento per l'API REST di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.

Suggerimento

È possibile usare Postman per provare le chiamate API REST descritte in questo articolo. Scaricare la raccolta Postman di IoT Central e importarla in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministratore.

Per informazioni su come gestire utenti e ruoli usando l'interfaccia utente di IoT Central, vedere Gestire utenti e ruoli nell'applicazione IoT Central.

Gestire i ruoli

L'API REST consente di elencare i ruoli definiti nell'applicazione IoT Central. Usare la richiesta seguente per recuperare un elenco di ID ruolo dall'applicazione:

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

La risposta a questa richiesta è simile all'esempio seguente che include i tre ruoli predefiniti e un ruolo personalizzato:

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

Nota

Questo comando mostra solo i ruoli associati a un'applicazione e non a un ruolo a livello di organizzazione personalizzato.

Gestisci utenti

L'API REST di IoT Central consente di:

Elencare gli utenti in un'applicazione
Recuperare i dettagli di un singolo utente
Creazione di un utente
Modificare un utente
Eliminare un utente

Elencare gli utenti

Usare la richiesta seguente per recuperare un elenco di utenti dall'applicazione:

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

La risposta a questa richiesta è simile all'esempio seguente. I valori del ruolo identificano l'ID ruolo a cui l'utente è associato:

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

Ottenere un utente

Usare la richiesta seguente per recuperare i dettagli di un singolo utente dall'applicazione:

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

La risposta a questa richiesta è simile all'esempio seguente. Il valore del ruolo identifica l'ID ruolo a cui l'utente è associato:

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

Creazione di un utente

Usare la richiesta seguente per creare un utente nell'applicazione. L'ID e il messaggio di posta elettronica devono essere univoci nell'applicazione:

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

Nel corpo della richiesta seguente, il role valore è per il ruolo dell'operatore recuperato in precedenza:

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

La risposta a questa richiesta è simile all'esempio seguente. Il valore del ruolo identifica il ruolo a cui è associato l'utente:

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

È anche possibile aggiungere un utente dell'entità servizio utile se è necessario usare l'autenticazione dell'entità servizio per le chiamate API REST. Per altre informazioni, vedere Aggiungere o aggiornare un utente dell'entità servizio.

Modificare il ruolo di un utente

Usare la richiesta seguente per modificare il ruolo assegnato all'utente. In questo esempio viene usato l'ID del ruolo generatore recuperato in precedenza:

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

Corpo della richiesta. Il valore è per il ruolo generatore recuperato in precedenza:

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

La risposta a questa richiesta è simile all'esempio seguente:

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

Eliminare un utente

Usare la richiesta seguente per eliminare un utente:

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

Passaggi successivi

Dopo aver appreso come gestire utenti e ruoli con l'API REST, un passaggio successivo consigliato consiste nell'usare l'API REST di IoT Central per gestire le organizzazioni.

Share via