Come usare l'API REST di IoT Central per gestire i dispositivi

Articolo
09/03/2023

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per gestire i dispositivi 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.

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 è necessario impostare variabili come il sottodominio dell'app e il token di amministratore.

Per informazioni su come gestire i dispositivi usando l'interfaccia utente di IoT Central, vedere Gestire i singoli dispositivi nell'applicazione Azure IoT Central.

API REST dei dispositivi

L'API REST di IoT Central consente di:

Aggiungere un dispositivo all'applicazione
Aggiornare un dispositivo nell'applicazione
Ottenere un elenco dei dispositivi nell'applicazione
Ottenere un dispositivo in base all'ID
Ottenere una credenziale del dispositivo
Eliminare un dispositivo nell'applicazione
Filtrare l'elenco dei dispositivi nell'applicazione

Aggiungere un dispositivo

Usare la richiesta seguente per creare un nuovo dispositivo.

PUT https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

L'esempio seguente mostra un corpo della richiesta che aggiunge un dispositivo per un modello di dispositivo. È possibile ottenere i template dettagli dalla pagina dei modelli di dispositivo nell'interfaccia utente dell'applicazione IoT Central.

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

Il corpo della richiesta include alcuni campi obbligatori:

@displayName: nome visualizzato del dispositivo.
@enabled: dichiara che questo oggetto è un'interfaccia.
@etag: ETag usato per evitare conflitti negli aggiornamenti dei dispositivi.
simulated: il dispositivo è simulato?
template : definizione del modello di dispositivo per il dispositivo.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Ottenere un dispositivo

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

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Nota

È possibile ottenere dall'interfaccia deviceId utente dell'applicazione IoT Central passando il puntatore del mouse su un dispositivo.

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

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

La tabella seguente illustra il mapping del valore di stato per un dispositivo nell'interfaccia utente ai valori usati dall'API REST per interagire con i dispositivi:

Stato del dispositivo dell'interfaccia utente	Note	OTTENERE l'API REST
In attesa di approvazione	L'opzione di approvazione automatica è disabilitata nel gruppo di connessione del dispositivo e il dispositivo non è stato aggiunto tramite l'interfaccia utente. Un utente deve approvare manualmente il dispositivo tramite l'interfaccia utente prima di poterlo usare.	`Provisioned: false` `Enabled: false`
Registrato	Un dispositivo è stato approvato automaticamente o manualmente.	`Provisioned: false` `Enabled: true`
Sottoposto a provisioning	È stato effettuato il provisioning del dispositivo e può connettersi all'applicazione IoT Central.	`Provisioned: true` `Enabled: true`
Bloccato	Il dispositivo non può connettersi all'applicazione IoT Central. È possibile bloccare un dispositivo che si trova in uno qualsiasi degli altri stati.	`Provisioned:` Dipende `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Ottenere le credenziali del dispositivo

Usare la richiesta seguente per recuperare le credenziali di un dispositivo dall'applicazione:

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

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

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

Aggiornare un dispositivo

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Il corpo della richiesta di esempio seguente modifica il enabled campo in false:

{
  "enabled": false
}

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

Eliminare un dispositivo

Usare la richiesta seguente per eliminare un dispositivo:

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Elencare i dispositivi

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

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Assegnare un manifesto della distribuzione

Se si aggiunge un dispositivo IoT Edge, è possibile usare l'API per assegnare un manifesto della distribuzione IoT Edge al dispositivo. Per altre informazioni, vedere Assegnare un manifesto di distribuzione a un dispositivo.

Usare i filtri ODATA

Nella versione di anteprima dell'API (api-version=2022-10-31-preview) è possibile usare i filtri ODATA per filtrare e ordinare i risultati restituiti dall'API dei dispositivi dell'elenco.

maxpagesize

Utilizzare maxpagesize per impostare le dimensioni dei risultati, la dimensione massima restituita del risultato è 100, la dimensione predefinita è 25.

Usare la richiesta seguente per recuperare i primi 10 dispositivi dall'applicazione:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

La risposta include un valore nextLink che è possibile usare per recuperare la pagina successiva dei risultati.

filter

Usare il filtro per creare espressioni che filtrano l'elenco di dispositivi. La tabella seguente illustra gli operatori di confronto che è possibile usare:

Operatore di confronto	Simbolo	Esempio
Uguale a	eq	`id eq 'device1' and scopes eq 'redmond'`
Non uguale a	ne	`Enabled ne true`
Minore o uguale a	le	`id le '26whl7mure6'`
Minore di	lt	`id lt '26whl7mure6'`
Maggiore o uguale a	ge	`id ge '26whl7mure6'`
Maggiore di	gt	`id gt '26whl7mure6'`

La tabella seguente illustra gli operatori logici che è possibile usare nelle espressioni di filtro :

Operatore logic	Simbolo	Esempio
AND	e	`id eq 'device1' and enabled eq true`
OR	oppure	`id eq 'device1' or simulated eq false`

Attualmente, il filtro funziona con i campi del dispositivo seguenti:

FieldName	Tipo	Descrizione
`id`	string	ID dispositivo
`displayName`	string	Nome visualizzato del dispositivo
`enabled`	boolean	Stato abilitato del dispositivo
`provisioned`	boolean	Stato del provisioning del dispositivo
`simulated`	boolean	Stato simulato del dispositivo
`template`	string	ID modello di dispositivo
`scopes`	string	ID organizzazione

funzioni supportate dal filtro:

Attualmente, l'unica funzione di filtro supportata per gli elenchi di dispositivi è la contains funzione :

filter=contains(displayName, 'device1')

Nell'esempio seguente viene illustrato come recuperare tutti i dispositivi in cui il nome visualizzato contiene la stringa thermostat:

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

orderby

Usare orderby per ordinare i risultati. Attualmente , orderby consente di ordinare solo in displayName. Per impostazione predefinita, orderby ordina in ordine crescente. Usare desc per ordinare in ordine decrescente, ad esempio:

orderby=displayName
orderby=displayName desc

L'esempio seguente illustra come recuperare tutti i modelli di dispositivo in cui il risultato viene ordinato in base displayName a :

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

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

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

È anche possibile combinare due o più filtri.

Nell'esempio seguente viene illustrato come recuperare i primi tre dispositivi in cui il nome visualizzato contiene la stringa Thermostat.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

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

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

Gruppi di dispositivi

È possibile creare gruppi di dispositivi in un'applicazione IoT Central per monitorare i dati aggregati, usarli con i processi e gestire l'accesso. I gruppi di dispositivi sono definiti da un filtro che seleziona i dispositivi da aggiungere al gruppo. È possibile creare gruppi di dispositivi nel portale di IoT Central o usando l'API.

Aggiungere un gruppo di dispositivi

Usare la richiesta seguente per creare un nuovo gruppo di dispositivi.

PUT https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Quando si crea un gruppo di dispositivi, si definisce un oggetto filter che seleziona i dispositivi da aggiungere al gruppo. Un filter oggetto identifica un modello di dispositivo e tutte le proprietà da associare. Nell'esempio seguente viene creato un gruppo di dispositivi che contiene tutti i dispositivi associati al modello "dtmi:modelDefinition:dtdlv2", in cui la provisioned proprietà è true

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Il corpo della richiesta include alcuni campi obbligatori:

@displayName: nome visualizzato del gruppo di dispositivi.
@filter: query che definisce i dispositivi che devono trovarsi in questo gruppo.
@etag: ETag usato per evitare conflitti negli aggiornamenti dei dispositivi.
description: breve riepilogo del gruppo di dispositivi.

Il campo organizzazioni viene usato solo quando un'applicazione ha una gerarchia dell'organizzazione definita. Per altre informazioni sulle organizzazioni, vedere Gestire le organizzazioni IoT Central

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

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Ottenere un gruppo di dispositivi

Usare la richiesta seguente per recuperare i dettagli di un gruppo di dispositivi dall'applicazione:

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

deviceGroupId: ID univoco per il gruppo di dispositivi.

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

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Aggiornare un gruppo di dispositivi

PATCH https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Il corpo della richiesta di esempio è simile all'esempio seguente che aggiorna l'oggetto displayName del gruppo di dispositivi:

{
  "displayName": "New group name"
}

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

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Eliminare un gruppo di dispositivi

Usare la richiesta seguente per eliminare un gruppo di dispositivi:

DELETE https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Elencare i gruppi di dispositivi

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

GET https://{your app subdomain}/api/deviceGroups?api-version=2022-07-31

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

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

Gruppi di registrazioni

I gruppi di registrazione vengono usati per gestire le opzioni di autenticazione del dispositivo nell'applicazione IoT Central. Per altre informazioni, vedere Concetti relativi all'autenticazione dei dispositivi in IoT Central.

Per informazioni su come creare e gestire i gruppi di registrazione nell'interfaccia utente, vedere Come connettere i dispositivi con certificati X.509 all'applicazione IoT Central.

Quando si crea un gruppo di registrazione per i dispositivi che usano certificati X.509, è prima necessario caricare il certificato radice o intermedio nell'applicazione IoT Central.

Generare certificati radice e dispositivo

In questa sezione vengono generati i certificati X.509 necessari per connettere un dispositivo a IoT Central.

Avviso

Questo modo di generare certificati X.509 è solo per i test. Per un ambiente di produzione è consigliabile usare il meccanismo ufficiale e sicuro per la generazione di certificati.

Passare allo script del generatore di certificati in Microsoft Azure IoT SDK per Node.js scaricato. Installare i pacchetti necessari:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Creare un certificato radice e quindi derivare un certificato del dispositivo eseguendo lo script:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Suggerimento

Un ID dispositivo può contenere lettere, numeri e il carattere -.

Questi comandi producono la radice e il certificato del dispositivo seguenti

nomefile	sommario
mytestrootcert_cert.pem	Parte pubblica del certificato X.509 radice
mytestrootcert_key.pem	Chiave privata per il certificato X.509 radice
mytestrootcert_fullchain.pem	L'intero portachiavi per il certificato X.509 radice.
mytestrootcert.pfx	File PFX per il certificato X.509 radice.
sampleDevice01_cert.pem	Parte pubblica del certificato X.509 del dispositivo
sampleDevice01_key.pem	Chiave privata per il certificato X.509 del dispositivo
sampleDevice01_fullchain.pem	L'intero portachiavi per il certificato X.509 del dispositivo.
sampleDevice01.pfx	File PFX per il certificato X.509 del dispositivo.

Prendere nota del percorso di questi file. Sarà necessario in un secondo momento.

Generare la versione codificata base-64 del certificato radice

Nella cartella nel computer locale che contiene i certificati generati, creare un file denominato convert.js e aggiungere il contenuto JavaScript seguente:

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

Eseguire il comando seguente per generare una versione di codifica base-64 del certificato:

node convert.js mytestrootcert_cert.pem

Prendere nota della versione codificata base-64 del certificato. Sarà necessario in un secondo momento.

Aggiungere un gruppo di registrazione X.509

Usare la richiesta seguente per creare un nuovo gruppo di registrazione con myx509eg come ID:

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

Nell'esempio seguente viene illustrato un corpo della richiesta che aggiunge un nuovo gruppo di registrazione X.509:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

Il corpo della richiesta include alcuni campi obbligatori:

@displayName: nome visualizzato del gruppo di registrazione.
@enabled: indica se i dispositivi che usano il gruppo possono connettersi a IoT Central.
@type: tipo di dispositivi che si connettono tramite il gruppo, o iotiotEdge.
attestation: meccanismo di attestazione per il gruppo di registrazione, symmetricKey o x509.

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

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

Aggiungere un certificato X.509 a un gruppo di registrazione

Usare la richiesta seguente per impostare il certificato X.509 primario del gruppo di registrazione myx509eg:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

voce - Immissione del certificato, o primarysecondary

Usare questa richiesta per aggiungere un certificato X.509 primario o secondario al gruppo di registrazione.

Nell'esempio seguente viene illustrato un corpo della richiesta che aggiunge un certificato X.509 a un gruppo di registrazione:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}

certificato: versione base-64 del certificato di cui è stato fatto nota in precedenza.
verificato: true se si attesta che il certificato è valido, false se è necessario dimostrare la validità del certificato.

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

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Generare codice di verifica per un certificato X.509

Usare la richiesta seguente per generare un codice di verifica per il certificato X.509 primario o secondario di un gruppo di registrazione.

Se è impostato verified su false nella richiesta precedente, usare la richiesta seguente per generare un codice di verifica per il certificato X.509 primario nel myx509eg gruppo di registrazione:

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

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

{
  "verificationCode": "<certificate-verification-code>"
}

Prendere nota del codice di verifica, è necessario nel passaggio successivo.

Generare il certificato di verifica

Usare il comando seguente per generare un certificato di verifica dal codice di verifica nel passaggio precedente:

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

Eseguire il comando seguente per generare una versione codificata base-64 del certificato:

node convert.js verification_cert.pem

Prendere nota della versione codificata base-64 del certificato. Sarà necessario in un secondo momento.

Verificare il certificato X.509 di un gruppo di registrazione

Usare la richiesta seguente per verificare il certificato X.509 primario del myx509eg gruppo di registrazione fornendo il certificato con il codice di verifica firmato:

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

Nell'esempio seguente viene illustrato un corpo della richiesta che verifica un certificato X.509:

{
  "certificate": "base64-verification-certificate"
}

Ottenere il certificato X.509 di un gruppo di registrazione

Usare la richiesta seguente per recuperare i dettagli del certificato X.509 di un gruppo di registrazione dall'applicazione:

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

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

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Eliminare un certificato X.509 da un gruppo di registrazione

Usare la richiesta seguente per eliminare il certificato X.509 primario da un gruppo di registrazione con ID myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Aggiungere un gruppo di registrazione della chiave simmetrica

Usare la richiesta seguente per creare un nuovo gruppo di registrazione con mysymmetric come ID:

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

Nell'esempio seguente viene illustrato un corpo della richiesta che aggiunge un nuovo gruppo di registrazione:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey"
  }
}

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

IoT Central genera le chiavi simmetriche primarie e secondarie quando si effettua questa chiamata API.

Ottenere un gruppo di registrazione

Usare la richiesta seguente per recuperare i dettagli di un gruppo di registrazione con mysymmetric come ID:

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

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Aggiornare un gruppo di registrazione

Usare la richiesta seguente per aggiornare un gruppo di registrazione.

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

Nell'esempio seguente viene illustrato un corpo della richiesta che aggiorna il nome visualizzato di un gruppo di registrazione:

{
  "displayName": "My new group name",
}

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

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Eliminare un gruppo di registrazione

Usare la richiesta seguente per eliminare un gruppo di registrazione con ID myx509eg:

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

Elencare i gruppi di registrazione

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

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

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

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}

Passaggi successivi

Dopo aver appreso come gestire i dispositivi con l'API REST, un passaggio successivo consigliato è Come controllare i dispositivi con l'API rest.

Share via

Come usare l'API REST di IoT Central per gestire i dispositivi

API REST dei dispositivi

Aggiungere un dispositivo

Ottenere un dispositivo

Ottenere le credenziali del dispositivo

Aggiornare un dispositivo

Eliminare un dispositivo

Elencare i dispositivi

Assegnare un manifesto della distribuzione

Usare i filtri ODATA

maxpagesize

filter

orderby

Gruppi di dispositivi

Aggiungere un gruppo di dispositivi

Ottenere un gruppo di dispositivi

Aggiornare un gruppo di dispositivi

Eliminare un gruppo di dispositivi

Elencare i gruppi di dispositivi

Gruppi di registrazioni

Creare un gruppo di registrazioni

Generare certificati radice e dispositivo

Generare la versione codificata base-64 del certificato radice

Aggiungere un gruppo di registrazione X.509

Aggiungere un certificato X.509 a un gruppo di registrazione

Generare codice di verifica per un certificato X.509

Generare il certificato di verifica

Verificare il certificato X.509 di un gruppo di registrazione

Ottenere il certificato X.509 di un gruppo di registrazione

Eliminare un certificato X.509 da un gruppo di registrazione

Aggiungere un gruppo di registrazione della chiave simmetrica

Ottenere un gruppo di registrazione

Aggiornare un gruppo di registrazione

Eliminare un gruppo di registrazione

Elencare i gruppi di registrazione

Passaggi successivi

Risorse aggiuntive