你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 IoT Central REST API 来管理设备

项目
03/06/2024

通过 IoT Central REST API，你可以开发与 IoT Central 应用程序集成的客户端应用程序。可以使用 REST API 来管理 IoT Central 应用程序中的设备。

每个 IoT Central REST API 调用都需要授权标头。有关详细信息，请参阅如何对 IoT Central REST API 调用进行身份验证和授权。

有关 IoT Central REST API 的参考文档，请参阅 Azure IoT Central REST API 参考。

提示

可以使用 Postman 尝试本文所述的 REST API 调用。下载 IoT Central Postman 集合并将其导入 Postman。在集合中需要设置变量，例如应用子域和管理员令牌。

要了解如何使用 IoT Central UI 管理设备，请参阅在 Azure IoT Central 应用程序中管理单个设备。

设备REST API

使用 IoT Central REST API 可进行以下操作：

将设备添加到应用程序
更新应用程序中的设备
获取应用程序中的设备列表
按 ID 获取设备
获取设备凭据
删除应用程序中的设备
筛选应用程序中的设备列表

添加设备

使用以下请求来创建新设备。

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

下面的示例演示了为设备模板添加设备的请求正文。可从 IoT Central 应用程序 UI 中的设备模板页获取 template 详细信息。

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

请求正文包含某些必填字段：

@displayName：设备的显示名称。
@enabled：声明此对象是接口。
@etag：用于防止设备更新中发生冲突的 ETag。
simulated：该设备是否为模拟设备？
template：设备的设备模板定义。

对此请求的响应如以下示例所示：

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

获取设备

使用以下请求从应用程序中检索设备的详细信息：

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

注意

你可将鼠标悬停在设备上，从 IoT Central 应用程序 UI 中获得 deviceId。

对此请求的响应如以下示例所示：

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

下表显示了 UI 中设备的状态值如何映射到 REST API 用来与设备交互的值：

UI 服务状态	说明	REST API Get
正在等待审批	自动审批选项在设备连接组中处于禁用状态，并且未通过 UI 添加设备。用户必须先通过 UI 手动批准设备，然后才能使用该设备。	`Provisioned: false` `Enabled: false`
已注册	会自动或手动批准设备。	`Provisioned: false` `Enabled: true`
已预配	设备已预配，可以连接到 IoT Central 应用程序。	`Provisioned: true` `Enabled: true`
被阻止	设备无法连接到 IoT Central 应用程序。可以阻止处于任何其他状态的设备。	`Provisioned:` 取决于 `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

获取设备凭据

使用以下请求从应用程序中检索设备的凭据：

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

对此请求的响应如以下示例所示：

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

更新设备

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

以下示例请求正文将 enabled 字段更改为 false：

{
  "enabled": false
}

对此请求的响应如以下示例所示：

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

删除设备

使用以下请求删除设备：

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

列出设备

使用以下请求从应用程序中检索设备列表：

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

对此请求的响应如以下示例所示：

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

分配部署清单

如果要添加 IoT Edge 设备，可以使用 API 将 IoT Edge 部署清单分配给设备。若要了解详细信息，请参阅将部署清单分配给设备。

使用 ODATA 筛选器

在 API 的预览版本 (api-version=2022-10-31-preview) 中，可以使用 ODATA 筛选器来筛选列表设备 API 返回的结果并对其进行排序。

maxpagesize

使用 maxpagesize 设置结果大小。返回的最大结果大小为 100，默认大小为 25。

使用以下请求从应用程序中检索某个排名前 10 的设备：

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

对此请求的响应如以下示例所示：

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

响应包含 nextLink 值，该值可用于检索下一页结果。

filter

使用 filter 创建用于筛选设备列表的表达式。下表显示了可以使用的比较运算符：

比较运算符	符号	示例
等于	eq	`id eq 'device1' and scopes eq 'redmond'`
不等于	ne	`Enabled ne true`
小于或等于	le	`id le '26whl7mure6'`
小于	lt	`id lt '26whl7mure6'`
大于或等于	ge	`id ge '26whl7mure6'`
大于	gt	`id gt '26whl7mure6'`

下表显示了可在 filter 表达式中使用的运算符：

逻辑运算符	符号	示例
AND	和	`id eq 'device1' and enabled eq true`
OR	或	`id eq 'device1' or simulated eq false`

目前，filter 适用于以下设备字段：

FieldName	类型	说明
`id`	string	设备 ID
`displayName`	string	设备显示名称
`enabled`	boolean	设备启用状态
`provisioned`	boolean	设备预配状态
`simulated`	boolean	设备模拟状态
`template`	string	设备模板 ID
`scopes`	string	组织 ID

filter 支持的函数：

目前，设备列表唯一支持的筛选器函数是 contains 函数：

filter=contains(displayName, 'device1')

以下示例演示如何检索显示名称包含字符串 thermostat 的所有设备：

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

对此请求的响应如以下示例所示：

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

使用 orderby 对结果进行排序。目前，orderby 仅允许针对 displayName 进行排序。默认情况下，orderby 按升序排序。使用 desc 按降序排序，例如：

orderby=displayName
orderby=displayName desc

下面的示例演示如何检索结果按 displayName 排序的所有设备模板：

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

对此请求的响应如以下示例所示：

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

还可以合并两个或多个筛选器。

下面的示例演示如何检索显示名称包含字符串 Thermostat 的前 3 台设备。

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

对此请求的响应如以下示例所示：

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

设备组

可以在 IoT Central 应用程序中创建设备组来监视聚合数据、与作业一起使用和管理访问权限。设备组是按筛选器定义的，该筛选器会选择要添加到组的设备。可以在 IoT Central 门户中或使用 API 创建设备组。

添加设备组

使用以下请求来创建新的设备组。

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

创建设备组时，需要定义 filter 以选择要添加到该组的设备。 filter 标识设备模板以及要匹配的任何属性。以下示例会创建设备组，其中包含与 provisioned 属性为 true 的“dtmi:modelDefinition:dtdlv2”模板关联的所有设备。

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

请求正文包含某些必填字段：

@displayName：设备组的显示名称。
@filter：用于定义应包含在此组中的设备的查询。
@etag：用于防止设备更新中发生冲突的 ETag。
description：设备组的简短摘要。

只有在应用程序定义了组织层次结构时，才使用“组织”字段。若要详细了解组织，请参阅管理 IoT Central 组织。

对此请求的响应如以下示例所示：

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

获取设备组

使用以下请求从应用程序中检索设备组的详细信息：

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

deviceGroupId - 设备组的唯一 ID。

对此请求的响应如以下示例所示：

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

更新设备组

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

示例请求正文类似于以下示例，该示例更新设备组的 displayName：

{
  "displayName": "New group name"
}

对此请求的响应如以下示例所示：

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

删除设备组

使用以下请求删除设备组：

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

列出设备组

使用以下请求从应用程序中检索设备组列表：

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

对此请求的响应如以下示例所示：

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

注册组

使用注册组管理 IoT Central 应用程序中的设备身份验证选项。若要了解详细信息，请参阅 IoT Central 中的设备身份验证概念。

若要了解如何在 UI 中创建和管理注册组，请参阅如何将使用 X.509 证书的设备连接到 IoT Central 应用程序。

为使用 X.509 证书的设备创建注册组时，首先需要将根证书或中间证书上传到 IoT Central 应用程序。

生成根证书和设备证书

在本部分，我们生成将设备连接到 IoT Central 所需的 X.509 证书。

警告

这种生成 X.509 证书的方法仅用于测试。对于生产环境，应使用官方的安全机制来生成证书。

导航到你已下载的用于 Node.js 的 Microsoft Azure IoT SDK 中的证书生成器脚本。安装所需的包：
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
创建根证书，然后通过运行脚本派生设备证书：
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
提示

设备 ID 中可以包含字母、数字和 - 字符。

这些命令会生成以下根和设备证书：

filename	内容
mytestrootcert_cert.pem	根 X.509 证书的公共部分
mytestrootcert_key.pem	根 X.509 证书的私钥
mytestrootcert_fullchain.pem	根 X.509 证书的整个密钥链。
mytestrootcert.pfx	根 X.509 证书的 PFX 文件。
sampleDevice01_cert.pem	设备 X.509 证书的公共部分
sampleDevice01_key.pem	设备 X.509 证书的私钥
sampleDevice01_fullchain.pem	设备 X.509 证书的整个密钥链。
sampleDevice01.pfx	设备 X.509 证书的 PFX 文件。

请记下这些文件的位置。稍后需要用到此信息。

生成根证书的 Base-64 编码版本

在本地计算机上包含所生成证书的文件夹中，创建名为 convert.js 的文件，并添加以下 JavaScript 内容：

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

运行以下命令以生成证书的 Base-64 编码版本：

node convert.js mytestrootcert_cert.pem

记下证书的 Base-64 编码版本。稍后需要用到此信息。

添加 X.509 注册组

使用以下请求创建 ID 为 myx509eg 的新注册组：

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

以下示例显示了一个请求正文，该正文添加了一个新的 X.509 注册组：

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

请求正文包含某些必填字段：

@displayName：注册组的显示名称。
@enabled：是否允许使用此组的设备连接到 IoT Central。
@type：通过此组连接的设备的类型，为 iot 或 iotEdge。
attestation：注册组的证明机制，为 symmetricKey 或 x509。

对此请求的响应如以下示例所示：

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

将 X.509 证书添加到注册组

使用以下请求设置 myx509eg 注册组的主要 X.509 证书：

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

使用此请求将主要的或次要的 X.509 证书添加到注册组。

以下示例显示了向注册组添加 X.509 证书的请求正文：

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

certificate - 你之前记下的证书的 Base-64 版本。
verified - 如果证明证书有效，则为 true；如果需要证明证书的有效性，则为 false。

对此请求的响应如以下示例所示：

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

为 X.509 证书生成验证码

使用以下请求为注册组的主要或次要 X.509 证书生成验证码。

如果在上一个请求中将 verified 设置为 false，请使用以下请求为 myx509eg 注册组中的主要 X.509 证书生成验证码：

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

对此请求的响应如以下示例所示：

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

请记下验证码，你需要在下一步骤中用到它。

生成验证证书

使用以下命令从上一步骤中的验证码生成验证证书：

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

运行以下命令以生成证书的 Base-64 编码版本：

node convert.js verification_cert.pem

记下证书的 Base-64 编码版本。稍后需要用到此信息。

验证注册组的 X.509 证书

使用以下请求来验证 myx509eg 注册组的主要 X.509 证书，方法是为证书提供签名的验证码：

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

以下示例演示了验证 X.509 证书的请求正文：

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

获取注册组的 X.509 证书

使用以下请求从应用程序检索注册组的 X.509 证书的详细信息：

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

对此请求的响应如以下示例所示：

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

从注册组中删除 X.509 证书

使用以下请求从 ID 为 myx509eg 的注册组删除主要 X.509 证书：

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

添加对称密钥注册组

使用以下请求创建 ID 为 mysymmetric 的新注册组：

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

以下示例显示了一个请求正文，该正文添加了一个新的注册组：

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

对此请求的响应如以下示例所示：

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

进行此 API 调用时，IoT Central 会生成主对称密钥和辅助对称密钥。

获取注册组

使用以下请求检索 ID 为 mysymmetric 的注册组的详细信息：

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

对此请求的响应如以下示例所示：

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

更新注册组

使用以下请求更新注册组。

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

以下示例显示了更新注册组的显示名称的请求正文：

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

对此请求的响应如以下示例所示：

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

删除注册组

使用以下请求删除 ID 为 myx509eg 的注册组：

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

列出注册组

使用以下请求从应用程序中检索注册组列表：

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

对此请求的响应如以下示例所示：

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

如何使用 IoT Central REST API 来管理设备

设备REST API

添加设备

获取设备

获取设备凭据

更新设备

删除设备

列出设备

分配部署清单

使用 ODATA 筛选器

maxpagesize

filter

orderby

设备组

添加设备组

获取设备组

更新设备组

删除设备组

列出设备组

注册组

创建注册组

生成根证书和设备证书

生成根证书的 Base-64 编码版本

添加 X.509 注册组

将 X.509 证书添加到注册组

为 X.509 证书生成验证码

生成验证证书

验证注册组的 X.509 证书

获取注册组的 X.509 证书

从注册组中删除 X.509 证书

获取注册组

更新注册组

删除注册组

列出注册组

其他资源