Como usar a API REST do IoT Central para gerenciar dispositivos
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.
Dica
Você pode usar o Postman para experimentar as chamadas à API REST descritas neste artigo. Baixe a coleção do Postman do IoT Central 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 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.
Criar um grupo de registro
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 installCrie 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 mytestrootcertDica
Uma identificação do dispositivo pode conter letras, números e o caractere
-.
Esses comandos produzem a seguinte raiz e os certificados do 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, sejaiotouiotEdge.attestation: o mecanismo de atestado para o grupo de registro, sejasymmetricKeyoux509.
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 –
truese você atestar que o certificado é válido;falsese 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
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="
}
]
}
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de