Como usar a API REST do IoT Central para gerenciar dispositivos

Artigo
03/05/2024

A API REST do IoT Central permite desenvolver aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para gerenciar dispositivos em seu aplicativo IoT Central.

Cada chamada à API REST do IoT Central requer um cabeçalho de autorização. Para saber mais, consulte Como autenticar e autorizar chamadas de API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, consulte Referência da API REST do Azure IoT Central.

Gorjeta

Você pode usar o Postman para experimentar as chamadas de API REST descritas neste artigo. Faça o download da coleção IoT Central Postman e importe-a para o Postman. Na coleção, você precisará definir variáveis como o subdomínio do aplicativo e o token de administrador.

Para saber como gerenciar dispositivos usando a interface do usuário do IoT Central, consulte Gerenciar dispositivos individuais em seu aplicativo do Azure IoT Central.

API REST de dispositivos

A API REST do IoT Central permite:

Adicionar um dispositivo à sua aplicação
Atualizar um dispositivo na sua aplicação
Obter uma lista dos dispositivos na aplicação
Obter um dispositivo por ID
Obter uma credencial de dispositivo
Excluir um dispositivo em seu aplicativo
Filtrar a lista de dispositivos no aplicativo

Adicionar um dispositivo

Use a seguinte solicitação para criar um novo dispositivo.

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

O exemplo a seguir mostra um corpo de solicitação que adiciona um dispositivo para um modelo de dispositivo. Você pode obter os template detalhes na página de modelos de dispositivo na interface do usuário do aplicativo IoT Central.

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

O corpo da solicitação tem alguns campos obrigatórios:

@displayName: Nome de exibição do dispositivo.
@enabled: Declara que este objeto é uma interface.
@etag: ETag usado para evitar conflitos em atualizações de dispositivos.
simulated: O dispositivo é simulado?
template : A definição de modelo de dispositivo para o dispositivo.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Obter um dispositivo

Use a seguinte solicitação para recuperar detalhes de um dispositivo do seu aplicativo:

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

Nota

Você pode obter a deviceId interface do usuário do aplicativo IoT Central passando o mouse sobre um dispositivo.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

A tabela a seguir mostra como o valor de status de um dispositivo na interface do usuário mapeia para os valores usados pela API REST para interagir com dispositivos:

Status do dispositivo da interface do usuário	Notas	Obter API REST
Aguardando aprovação	A opção de aprovação automática está desativada no grupo de conexões de dispositivo e o dispositivo não foi adicionado por meio da interface do usuário. Um usuário deve aprovar manualmente o dispositivo por meio da interface do usuário antes que ele possa ser usado.	`Provisioned: false` `Enabled: false`
Registado	Um dispositivo foi aprovado automaticamente ou manualmente.	`Provisioned: false` `Enabled: true`
Aprovisionado	O dispositivo foi provisionado e pode se conectar ao seu aplicativo IoT Central.	`Provisioned: true` `Enabled: true`
Bloqueado	O dispositivo não tem permissão para se conectar ao seu aplicativo IoT Central. Você pode bloquear um dispositivo que esteja em qualquer um dos outros estados.	`Provisioned:` depende de `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Obter as credenciais do dispositivo

Use a seguinte solicitação para recuperar credenciais de um dispositivo do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Atualizar um dispositivo

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

O seguinte corpo de solicitação de exemplo altera o enabled campo para false:

{
  "enabled": false
}

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Eliminar um dispositivo

Use a seguinte solicitação para excluir um dispositivo:

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

Listar dispositivos

Use a seguinte solicitação para recuperar uma lista de dispositivos do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Atribuir um manifesto de implantação

Se você estiver adicionando um dispositivo IoT Edge, poderá usar a API para atribuir um manifesto de implantação do IoT Edge ao dispositivo. Para saber mais, consulte Atribuir um manifesto de implantação a um dispositivo.

Usar filtros ODATA

Na versão de visualização da API (api-version=2022-10-31-preview), você pode usar filtros ODATA para filtrar e classificar os resultados retornados pela API de dispositivos de lista.

maxpagesize

Use maxpagesize para definir o tamanho do resultado. O tamanho máximo do resultado retornado é 100 e o tamanho padrão é 25.

Use a seguinte solicitação para recuperar um dispositivo top 10 do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

A resposta inclui um valor nextLink que você pode usar para recuperar a próxima página de resultados.

filtrar

Use filter para criar expressões que filtram a lista de dispositivos. A tabela a seguir mostra os operadores de comparação que você pode usar:

Operador de comparação	Símbolo	Exemplo
Igual a	eq	`id eq 'device1' and scopes eq 'redmond'`
Diferente de	ne	`Enabled ne true`
Menor ou igual	le	`id le '26whl7mure6'`
Menor que	lt	`id lt '26whl7mure6'`
Maior que ou igual	ge	`id ge '26whl7mure6'`
Maior que	gt	`id gt '26whl7mure6'`

A tabela a seguir mostra os operadores lógicos que você pode usar em expressões de filtro :

Operador Lógico	Símbolo	Exemplo
AND	e	`id eq 'device1' and enabled eq true`
OR	ou	`id eq 'device1' or simulated eq false`

Atualmente, o filtro funciona com os seguintes campos de dispositivo:

Nome do campo	Tipo	Description
`id`	string	ID do Dispositivo
`displayName`	string	Nome de exibição do dispositivo
`enabled`	boolean	Status do dispositivo ativado
`provisioned`	boolean	Status do dispositivo provisionado
`simulated`	boolean	Estado simulado do dispositivo
`template`	string	ID do modelo de dispositivo
`scopes`	string	ID da organização

Funções suportadas pelo filtro:

Atualmente, a única função de filtro suportada para listas de dispositivos é a contains função:

filter=contains(displayName, 'device1')

O exemplo a seguir mostra como recuperar todos os dispositivos onde o nome para exibição contém a cadeia de caracteres thermostat:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

encomendado por

Use orderby para classificar os resultados. Atualmente, orderby só permite classificar em displayName. Por padrão, orderby classifica em ordem crescente. Use desc para classificar em ordem decrescente, por exemplo:

orderby=displayName
orderby=displayName desc

O exemplo a seguir mostra como recuperar todos os modelos de dispositivo em que o resultado é classificado por displayName :

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Você também pode combinar dois ou mais filtros.

O exemplo a seguir mostra como recuperar os três principais dispositivos onde o nome para exibição contém a cadeia de caracteres Thermostat.

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Grupos de dispositivos

Você pode criar grupos de dispositivos em um aplicativo do IoT Central para monitorar dados agregados, usar com trabalhos e gerenciar o acesso. Os grupos de dispositivos são definidos por um filtro que seleciona os dispositivos a serem adicionados ao grupo. Você pode criar grupos de dispositivos no portal do IoT Central ou usando a API.

Adicionar um grupo de dispositivos

Use a solicitação a seguir para criar um novo grupo de dispositivos.

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

Ao criar um grupo de dispositivos, você define um filter que seleciona os dispositivos a serem adicionados ao grupo. A filter identifica um modelo de dispositivo e todas as propriedades a serem correspondidas. O exemplo a seguir cria um grupo de dispositivos que contém todos os dispositivos associados ao modelo "dtmi:modelDefinition:dtdlv2" onde a provisioned propriedade é true.

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

O corpo da solicitação tem alguns campos obrigatórios:

@displayName: Nome para exibição do grupo de dispositivos.
@filter: Consulta definindo quais dispositivos devem estar neste grupo.
@etag: ETag usado para evitar conflitos em atualizações de dispositivos.
description: Breve resumo do grupo de dispositivos.

O campo organizações só é usado quando um aplicativo tem uma hierarquia organizacional definida. Para saber mais sobre organizações, consulte Gerenciar organizações do IoT Central.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Obter um grupo de dispositivos

Use a seguinte solicitação para recuperar detalhes de um grupo de dispositivos do seu aplicativo:

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

deviceGroupId - ID exclusivo para o grupo de dispositivos.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Atualizar um grupo de dispositivos

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

O corpo da solicitação de exemplo se parece com o seguinte exemplo que atualiza o displayName do grupo de dispositivos:

{
  "displayName": "New group name"
}

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Excluir um grupo de dispositivos

Use a seguinte solicitação para excluir um grupo de dispositivos:

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

Listar grupos de dispositivos

Use a seguinte solicitação para recuperar uma lista de grupos de dispositivos do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Grupos de inscrição

Os grupos de registro são usados para gerenciar as opções de autenticação de dispositivo em seu aplicativo IoT Central. Para saber mais, consulte Conceitos de autenticação de dispositivo no IoT Central.

Para saber como criar e gerenciar grupos de registro na interface do usuário, consulte Como conectar dispositivos com certificados X.509 ao Aplicativo IoT Central.

Ao criar um grupo de registro para dispositivos que usam certificados X.509, primeiro você precisa carregar o certificado raiz ou intermediário para seu aplicativo IoT Central.

Gerar certificados raiz e de dispositivo

Nesta seção, você gera os certificados X.509 necessários para conectar um dispositivo ao IoT Central.

Aviso

Esta forma de gerar certificados X.509 é apenas para testes. Para um ambiente de produção, você deve usar seu mecanismo oficial e seguro para a geração de certificados.

Navegue até o script do gerador de certificados no SDK do Microsoft Azure IoT para Node.js você baixou. Instale os pacotes necessários:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Crie um certificado raiz e, em seguida, derive um certificado de dispositivo executando o script:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Gorjeta

Um ID de dispositivo pode conter letras, números e o - caractere.

Esses comandos produzem a seguinte raiz e os certificados de dispositivo:

filename	Índice
mytestrootcert_cert.pem	A parte pública do certificado X.509 raiz
mytestrootcert_key.pem	A chave privada para o certificado X.509 raiz
mytestrootcert_fullchain.pem	O conjunto de chaves para o certificado X.509 raiz.
mytestrootcert.pfx	O arquivo PFX para o certificado X.509 raiz.
sampleDevice01_cert.pem	A parte pública do certificado X.509 do dispositivo
sampleDevice01_key.pem	A chave privada para o certificado X.509 do dispositivo
sampleDevice01_fullchain.pem	O conjunto de chaves para o certificado X.509 do dispositivo.
sampleDevice01.pfx	O arquivo PFX para o certificado X.509 do dispositivo.

Anote a localização desses arquivos. Você precisa dele mais tarde.

Gerar a versão codificada em base 64 do certificado raiz

Na pasta da máquina local que contém os certificados gerados, crie um arquivo chamado convert.js e adicione o seguinte conteúdo JavaScript:

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

Execute o seguinte comando para gerar uma versão de codificação base-64 do certificado:

node convert.js mytestrootcert_cert.pem

Anote a versão codificada em base 64 do certificado. Você precisa dele mais tarde.

Adicionar um grupo de inscrição X.509

Use a seguinte solicitação para criar um novo grupo de inscrição com myx509eg a ID:

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

O exemplo a seguir mostra um corpo de solicitação que adiciona um novo grupo de registro X.509:

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

O corpo da solicitação tem alguns campos obrigatórios:

@displayName: Nome para exibição do grupo de inscrição.
@enabled: Se os dispositivos que usam o grupo têm permissão para se conectar ao IoT Central.
@type: Tipo de dispositivos que se conectam através do grupo, ou iotiotEdge.
attestation: O mecanismo de atestado para o grupo de inscrição, ou symmetricKeyx509.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Adicionar um certificado X.509 a um grupo de inscrição

Use a seguinte solicitação para definir o certificado X.509 primário do grupo de inscrição myx509eg:

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

Use essa solicitação para adicionar um certificado X.509 primário ou secundário ao grupo de inscrição.

O exemplo a seguir mostra um corpo de solicitação que adiciona um certificado X.509 a um grupo de registro:

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

certificado - A versão base-64 do certificado que você anotou anteriormente.
verificado - true se você atestar que o certificado é válido, false se você precisa provar a validade do certificado.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Gerar código de verificação para um certificado X.509

Use a solicitação a seguir para gerar um código de verificação para o certificado X.509 primário ou secundário de um grupo de inscrição.

Se você definir verified como false na solicitação anterior, use a seguinte solicitação para gerar um código de verificação para o certificado X.509 primário no myx509eg grupo de registro:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Anote o código de verificação, você precisa dele na próxima etapa.

Gerar o certificado de verificação

Use o seguinte comando para gerar um certificado de verificação a partir do código de verificação na etapa anterior:

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

Execute o seguinte comando para gerar uma versão codificada em base 64 do certificado:

node convert.js verification_cert.pem

Anote a versão codificada em base 64 do certificado. Você precisa dele mais tarde.

Verificar o certificado X.509 de um grupo de inscrição

Use a seguinte solicitação para verificar o certificado X.509 primário do grupo de inscrição, fornecendo o certificado com o código de myx509eg verificação assinado:

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

O exemplo a seguir mostra um corpo de solicitação que verifica um certificado X.509:

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

Obter certificado X.509 de um grupo de inscrição

Use a seguinte solicitação para recuperar detalhes do certificado X.509 de um grupo de inscrição do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Excluir um certificado X.509 de um grupo de inscrição

Use a seguinte solicitação para excluir o certificado X.509 primário de um grupo de inscrição com ID myx509eg:

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

Adicionar um grupo de inscrição de chave simétrica

Use a seguinte solicitação para criar um novo grupo de inscrição com mysymmetric a ID:

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

O exemplo a seguir mostra um corpo de solicitação que adiciona um novo grupo de registro:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

O IoT Central gera as chaves simétricas primária e secundária quando você faz essa chamada de API.

Obter um grupo de inscrição

Use a seguinte solicitação para recuperar detalhes de um grupo de inscrição com mysymmetric a ID:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Atualizar um grupo de inscrição

Use a solicitação a seguir para atualizar um grupo de inscrição.

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

O exemplo a seguir mostra um corpo de solicitação que atualiza o nome para exibição de um grupo de registro:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Excluir um grupo de inscrição

Use a seguinte solicitação para excluir um grupo de inscrição com ID myx509eg:

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

Listar grupos de inscrição

Use a seguinte solicitação para recuperar uma lista de grupos de inscrição do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Como usar a API REST do IoT Central para gerenciar dispositivos

API REST de dispositivos

Adicionar um dispositivo

Obter um dispositivo

Obter as credenciais do dispositivo

Atualizar um dispositivo

Eliminar um dispositivo

Listar dispositivos

Atribuir um manifesto de implantação

Usar filtros ODATA

maxpagesize

filtrar

encomendado por

Grupos de dispositivos

Adicionar um grupo de dispositivos

Obter um grupo de dispositivos

Atualizar um grupo de dispositivos

Excluir um grupo de dispositivos

Listar grupos de dispositivos

Grupos de inscrição

Criar um grupo de inscrição

Gerar certificados raiz e de dispositivo

Gerar a versão codificada em base 64 do certificado raiz

Adicionar um grupo de inscrição X.509

Adicionar um certificado X.509 a um grupo de inscrição

Gerar código de verificação para um certificado X.509

Gerar o certificado de verificação

Verificar o certificado X.509 de um grupo de inscrição

Obter certificado X.509 de um grupo de inscrição

Excluir um certificado X.509 de um grupo de inscrição

Obter um grupo de inscrição

Atualizar um grupo de inscrição

Excluir um grupo de inscrição

Listar grupos de inscrição

Recursos adicionais