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

  • Articolo

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 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.

Per informazioni su come gestire i dispositivi usando l'interfaccia utente di IoT Central, vedere Gestire 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 credenziali 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 del dispositivo.
  • 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 deviceId dall'interfaccia 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 dell'approvazione L'opzione di approvazione automatica è disabilitata nel gruppo di connessioni 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
Bloccati Il dispositivo non è autorizzato a 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 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 di elenco.

maxpagesize

Utilizzare maxpagesize per impostare le dimensioni dei risultati. La dimensione massima dei risultati restituita è 100 e la dimensione predefinita è 25.

Usare la richiesta seguente per recuperare un dispositivo top 10 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 dei dispositivi. La tabella seguente illustra gli operatori di confronto che è possibile usare:

Operatore di confronto Simbolo Esempio
Equals eq id eq 'device1' and scopes eq 'redmond'
Diverso da 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:

Operatori logici Simbolo Esempio
E and id eq 'device1' and enabled eq true
OPPURE or id eq 'device1' or simulated eq false

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

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

funzioni supportate dai filtri:

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 displayName base 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 filter oggetto 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 contenente 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 quali dispositivi devono trovarsi in questo gruppo.
  • @etag: ETag usato per evitare conflitti negli aggiornamenti del dispositivo.
  • description: breve riepilogo del gruppo di dispositivi.

Il campo organizations 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.

Creare un gruppo di registrazioni

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.

  1. 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

  2. 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 seguente e i certificati del dispositivo:

filename 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 con codifica Base 64 del certificato radice

Nella cartella del 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 con codifica base 64 del certificato:

node convert.js mytestrootcert_cert.pem

Prendere nota della versione con codifica 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

L'esempio seguente mostra 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, iot o iotEdge.
  • 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

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

L'esempio seguente mostra un corpo della richiesta che aggiunge un certificato X.509 a un gruppo di registrazioni:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}
  • certificate: versione base 64 del certificato annotato 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 il 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 si imposta su verified false nella richiesta precedente, usare la richiesta seguente per generare un codice di verifica per il certificato X.509 primario nel myx509eg gruppo di registrazioni:

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 con codifica Base 64 del certificato:

node convert.js verification_cert.pem

Prendere nota della versione con codifica 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

L'esempio seguente mostra 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 registrazioni con ID myx509eg:

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

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

L'esempio seguente mostra 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="
        }
    ]
}