如何使用 IoT Central REST API 來管理裝置

發行項
05/13/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以在 IoT Central 應用程式中使用 REST API 來管理裝置。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入了解，請參閱如何驗證和授權 IoT Central REST API 呼叫。

如需 IoT Central REST API 的參考文件，請參閱 Azure IoT Central REST API 參考。

若要了解如何使用 IoT Central UI 來管理裝置，請參閱在 IoT Central 應用程式中管理個別裝置。

裝置 REST API

IoT Central REST API \(英文\) 可讓您：

在您的應用程式中新增裝置
在您的應用程式中更新裝置
取得應用程式中的裝置清單
依識別碼取得裝置
取得裝置認證
在您的應用程式中刪除裝置
篩選應用程式中的裝置清單

新增裝置

使用下列要求來建立新的裝置。

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 建立運算式以篩選裝置清單。下表顯示您可以使用的比較運算子：

比較運算子	符號	範例
Equals	eq	`id eq 'device1' and scopes eq 'redmond'`
不等於	ne	`Enabled ne true`
Less than or equals	le	`id le '26whl7mure6'`
小於	lt	`id lt '26whl7mure6'`
Greater than or equals	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	裝置識別碼
`displayName`	string	裝置顯示名稱
`enabled`	boolean	裝置啟用狀態
`provisioned`	boolean	裝置佈建狀態
`simulated`	boolean	裝置模擬狀態
`template`	string	裝置範本識別碼
`scopes`	string	組織識別碼

篩選支援的函式：

目前，裝置清單唯一支援的篩選函式是 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 字串的前三名裝置。

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 會識別裝置範本和要比對的任何屬性。下列範例會建立裝置群組，其中包含與屬性為 true之「dtmi：modelDefinition：dtdlv2」範本provisioned相關聯的所有裝置。

{
  "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": "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
```
提示

裝置識別碼可以包含字母、數字和 - 字元。

這些命令會產生下列根目錄和裝置憑證：

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 註冊群組

使用下列要求來建立以 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 憑證

使用下列要求，從識別碼為 myx509eg 的註冊群組中刪除主要 X.509 憑證：

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

新增對稱金鑰註冊群組

使用下列要求來建立以 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 會產生主要和次要對稱金鑰。

取得註冊群組

使用下列要求來擷取以 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="
}

刪除註冊群組

使用下列要求來刪除識別碼為 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

篩選器

orderby

裝置群組

新增裝置群組

取得裝置群組

更新裝置群組

刪除裝置群組

列出裝置群組

註冊群組

建立註冊群組

產生根憑證和裝置憑證

產生根憑證的 base-64 編碼版本

新增 X.509 註冊群組

將 X.509 憑證新增至註冊群組

產生 X.509 憑證的驗證碼

產生驗證憑證

確認註冊群組的 X.509 憑證

取得註冊群組的 X.509 憑證

從註冊群組中刪除 X.509 憑證

新增對稱金鑰註冊群組

取得註冊群組

更新註冊群組

刪除註冊群組

列出註冊群組

意見反應

其他資源