Como usar a API REST do IoT Central para gerenciar dispositivos

Artigo
03/07/2024

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

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

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

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 ao seu aplicativo
Atualizar um dispositivo em seu aplicativo
obter uma lista dos dispositivos no aplicativo;
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 solicitação a seguir para criar um dispositivo.

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

O exemplo a seguir mostra um corpo da solicitação que adiciona um dispositivo para um modelo de dispositivo. Você pode obter os detalhes template na página de modelos de dispositivo na interface do usuário do aplicativo do 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 esse objeto é uma interface.
@etag: ETag usada para evitar conflitos em atualizações de dispositivo.
simulated: O dispositivo é simulado?
template: a definição de modelo de dispositivo para o dispositivo.

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Obter um dispositivo

Usar a solicitação a seguir para recuperar detalhes de um dispositivo do seu aplicativo:

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

Observação

Você pode obter o deviceId da Interface do Usuário do Aplicativo IoT Central passando o mouse sobre um dispositivo.

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "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 é mapeado para os valores usados pela API REST para interagir com dispositivos:

Status do dispositivo de interface do usuário	Observações	Obtenção da API REST
Aguardando aprovação	A opção de aprovação automática está desabilitada no grupo de conexões do 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`
Registrada	Um dispositivo foi aprovado automaticamente ou manualmente.	`Provisioned: false` `Enabled: true`
Provisionado	O dispositivo foi provisionado e pode se conectar ao aplicativo IoT Central.	`Provisioned: true` `Enabled: true`
Bloqueado	O dispositivo não tem permissão para se conectar ao 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 credenciais do dispositivo

Usar a solicitação a seguir 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 é parecida com o seguinte exemplo:

{
    "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 corpo da solicitação de exemplo a seguir altera o campo enabled para false:

{
  "enabled": false
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Excluir um dispositivo

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

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

Lista de dispositivos

Use a solicitação a seguir 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 é parecida com o seguinte exemplo:

{
    "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 do IoT Edge, poderá usar a API para atribuir um manifesto de implantação do IoT Edge ao dispositivo. Para saber mais, confira Atribuir um manifesto de implantação a um dispositivo.

Usar filtros ODATA

Na versão prévia 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 o maxpagesize para definir o tamanho do resultado. O tamanho máximo de resultado retornado é 100 e o tamanho padrão é 25.

Usar a solicitação a seguir para recuperar os 10 principais dispositivos de seu aplicativo:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "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 de nextLink que você pode usar para recuperar a próxima página de resultados.

filtro

Use filtrar para criar expressões que filtram a lista de dispositivos. A seguinte tabela 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 a	le	`id le '26whl7mure6'`
Menor que	lt	`id lt '26whl7mure6'`
Maior ou igual a	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 filtrar:

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

Atualmente, filtrar funciona com os seguintes campos de dispositivo:

FieldName	Tipo	Descrição
`id`	string	ID do dispositivo
`displayName`	string	Nome de exibição do dispositivo
`enabled`	boolean	Status de dispositivo habilitado
`provisioned`	boolean	Status de dispositivo provisionado
`simulated`	boolean	Status de dispositivo simulado
`template`	string	ID do modelo de dispositivo
`scopes`	string	ID da organização

Funções compatíveis com filtrar:

No momento, a única função de filtro com suporte para listas de dispositivos é a função contains:

filter=contains(displayName, 'device1')

O seguinte exemplo mostra como recuperar todos os modelos de dispositivo em que o nome de 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 é parecida com o seguinte exemplo:

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

Use orderby para classificar os resultados. Atualmente, orderby só permite que você classifique em displayName. Por padrão, orderby classifica em ordem crescente. Use desc para classificá-los em ordem decrescente, por exemplo:

orderby=displayName
orderby=displayName desc

O seguinte exemplo mostra como recuperar todos os modelos de dispositivo em que o resultado está classificado por displayName:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "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 em que o nome de 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 é parecida com o seguinte exemplo:

{
  "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 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. Um filter identifica um modelo de dispositivo e qualquer propriedade a ser correspondente. O exemplo a seguir cria um grupo de dispositivos que contém todos os dispositivos associados ao modelo "dtmi:modelDefinition:dtdlv2" em que a propriedade provisioned é 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 de exibição do grupo de dispositivos.
@filter: consulta que definine quais dispositivos devem estar nesse grupo.
@etag: ETag usada para evitar conflitos em atualizações de dispositivo.
description: resumo curto do grupo de dispositivos.

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Criar um grupo de dispositivos

Use a solicitação a seguir 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 exclusiva para o grupo de dispositivos.

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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 exemplo a seguir que atualiza o displayName do grupo de dispositivos:

{
  "displayName": "New group name"
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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 solicitação a seguir 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 é parecida com o seguinte exemplo:

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

Grupos de registros são usados para gerenciar as opções de autenticação de dispositivo no aplicativo do IoT Central. Para saber mais, confira Conceitos de autenticação de dispositivo no IoT Central.

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

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

Gerar certificados de dispositivo e de raiz

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

Aviso

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

Navegue até o script do gerador de certificado no SDK do Microsoft Azure IoT para Node.js que você baixou. Instale os pacotes necessários:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Crie um certificado raiz e 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
```
Dica

Uma identificação do dispositivo pode conter letras, números e o caractere -.

Esses comandos produzem os seguintes certificados raiz e de dispositivo:

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

Anote o local desses arquivos. Isso será necessário mais tarde.

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

Na pasta no computador 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 comando a seguir 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. Isso será necessário mais tarde.

Adicionar um grupo de registros X.509

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

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

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

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

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

@displayName: nome de exibição do grupo de registros.
@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 por meio do grupo, seja iot ou iotEdge.
attestation: o mecanismo de atestado para o grupo de registro, seja symmetricKey ou x509.

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Use a solicitação a seguir para definir o certificado X.509 primário do grupo de registros 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 registros.

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

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

certificate – a versão base 64 do certificado que você anotou anteriormente.
verified – true se você atestar que o certificado é válido; false se você precisar comprovar a validade do certificado.

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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 registros.

Se você definiu 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 grupo de registros myx509eg:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Anote o código de verificação, pois vai precisar dele na próxima etapa.

Gerar o certificado de verificação

Use o comando a seguir 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 comando a seguir para gerar uma versão de codificação base 64 do certificado:

node convert.js verification_cert.pem

Anote a versão codificada em base 64 do certificado. Isso será necessário mais tarde.

Verificar o certificado X.509 de um grupo de registros

Use a seguinte solicitação para verificar o certificado X.509 primário do grupo de registros myx509eg fornecendo o certificado com o código de 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 da solicitação que verifica um certificado X.509:

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

Obter o certificado X.509 de um grupo de registros

Use a solicitação a seguir para recuperar detalhes do certificado X.509 de um grupo de registros do aplicativo:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Excluir um certificado X.509 de um grupo de registros

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

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

Adicionar um grupo de registros de chave simétrica

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

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

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

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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árias e secundárias quando você faz essa chamada à API.

Obter um grupo de registros

Use a solicitação a seguir para recuperar detalhes de um grupo de registros com mysymmetric como a ID:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

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

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

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

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Use a solicitação a seguir para excluir um grupo de registros com a ID myx509eg:

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

Listar grupos de registros

Use a solicitação a seguir para recuperar uma lista de grupos de registros do aplicativo:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Compartilhar via

Como usar a API REST do IoT Central para gerenciar dispositivos

API REST de dispositivos

Adicionar um dispositivo

Obter um dispositivo

Obter credenciais do dispositivo

atualizar um dispositivo;

Excluir um dispositivo

Lista de dispositivos

Atribuir um manifesto de implantação

Usar filtros ODATA

maxpagesize

filtro

orderby

Grupos de dispositivos

Adicionar um grupo de dispositivos

Criar um grupo de dispositivos

Atualizar um grupo de dispositivos

Excluir um grupo de dispositivos

Listar grupos de dispositivos

Grupos de registro

Criar um grupo de registro

Gerar certificados de dispositivo e de raiz

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

Adicionar um grupo de registros X.509

Adicionar um certificado X.509 a um grupo de registros

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 registros

Obter o certificado X.509 de um grupo de registros

Excluir um certificado X.509 de um grupo de registros

Adicionar um grupo de registros de chave simétrica

Obter um grupo de registros

Atualizar um grupo de registros

Excluir um grupo de registros

Listar grupos de registros

Comentários

Recursos adicionais