Come autenticare e autorizzare le chiamate API REST IoT Central

Articolo
10/27/2023

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. Usare l'API REST per usare le risorse nell'applicazione IoT Central, ad esempio modelli di dispositivo, dispositivi, processi, utenti e ruoli.

Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione usata da IoT Central per determinare l'identità del chiamante e le autorizzazioni concesse dal chiamante all'interno dell'applicazione.

Questo articolo descrive i tipi di token che è possibile usare nell'intestazione dell'autorizzazione e come ottenerli. Le entità di sicurezza sono l'approccio consigliato per la gestione degli accessi per le API REST di IoT Central.

Tipi di token

Per accedere a un'applicazione IoT Central usando l'API REST, è possibile usare:

Token di connessione di Azure Active Directory. Un token di connessione è associato a un account utente o a un'entità servizio Microsoft Entra. Il token concede al chiamante le stesse autorizzazioni che l'utente o l'entità servizio hanno nell'applicazione IoT Central.
Token DELL'API IoT Central. Un token API è associato a un ruolo nell'applicazione IoT Central.

Usare un token di connessione associato all'account utente durante lo sviluppo e il test di automazione e script che usano l'API REST. Usare un token di connessione associato a un'entità servizio per l'automazione e gli script di produzione. Usare un token di connessione in preferenza a un token API per ridurre il rischio di perdite e problemi alla scadenza dei token.

Per altre informazioni su utenti e ruoli in IoT Central, vedere Gestire utenti e ruoli nell'applicazione IoT Central.

Ottenere un token di connessione

Per ottenere un token di connessione per l'account utente Microsoft Entra, usare i comandi seguenti dell'interfaccia della riga di comando di Azure:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Importante

Il az login comando è necessario anche se si usa Cloud Shell.

L'output JSON del comando precedente è simile all'esempio seguente:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

Il token di connessione è valido per circa un'ora, dopo il quale è necessario crearne uno nuovo.

Per ottenere un token di connessione per un'entità servizio, vedere Autenticazione dell'entità servizio.

Ottenere un token API

Per ottenere un token API, è possibile usare l'interfaccia utente di IoT Central o una chiamata API REST. Amministrazione istrator associati all'organizzazione radice e agli utenti assegnati al ruolo corretto possono creare token API.

Suggerimento

Le operazioni di creazione ed eliminazione sui token API vengono registrate nel log di controllo.

Nell'interfaccia utente di IoT Central:

Passare a Token API autorizzazioni>.
Fare clic su + Nuovo o Creare un token API.
Immettere un nome per il token e selezionare un ruolo e un'organizzazione.
Selezionare Genera.
IoT Central visualizza il token simile all'esempio seguente:

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

Questa schermata è l'unica volta che è possibile visualizzare il token API, se si perde, è necessario generarne uno nuovo.

Un token API è valido per circa un anno. È possibile generare token per ruoli predefiniti e personalizzati nell'applicazione IoT Central. L'organizzazione scelta quando si crea il token API determina i dispositivi a cui l'API ha accesso. Tutti i token API creati prima di aggiungere organizzazioni all'applicazione sono associati all'organizzazione radice.

È possibile eliminare i token API nell'interfaccia utente di IoT Central se è necessario revocare l'accesso.

Uso dell'API REST:

Usare l'API REST 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:

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

Usare l'API REST per creare un token API per un ruolo. Ad esempio, per creare un token API denominato operator-token per il ruolo operatore:

PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-07-31

Testo della richiesta:

{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

La risposta al comando precedente è simile al codice JSON seguente:

{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

Questa risposta è l'unica volta che si ha accesso al token API, se si perde, è necessario generarne uno nuovo.

È possibile usare l'API REST per elencare ed eliminare i token API in un'applicazione.

Usare un token di connessione

Per usare un token di connessione quando si effettua una chiamata API REST, l'intestazione dell'autorizzazione è simile all'esempio seguente:

Authorization: Bearer eyJ0eX...fNQ

Usare un token API

Per usare un token API quando si effettua una chiamata API REST, l'intestazione dell'autorizzazione è simile all'esempio seguente:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889

Passaggi successivi

Ora che si è appreso come autorizzare le chiamate API REST, un passaggio successivo consigliato consiste nell'usare l'API REST di IoT Central per eseguire query sui dispositivi.

Condividi tramite