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

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 參考。

提示

您可以使用 Postman 來試用本文中所述的 REST API 呼叫。 下載 IoT Central Postman 集合並匯入 Postman 中。 在該集合中，您必須設定變數，例如應用程式子網域和管理員權杖。

若要了解如何使用 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 取得
等候核准	自動核准選項會在裝置連線群組中停用，且未透過 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'
Not Equals	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'

下表顯示您可以在 篩選 運算式中使用的邏輯運算子：

邏輯運算子	符號	範例
和	及	id eq 'device1' and enabled eq true
OR	或	id eq 'device1' or simulated eq false

篩選 目前適用于下列 裝置欄位：

FieldName	類型	描述
id	字串	裝置識別碼
displayName	字串	裝置顯示名稱
enabled	boolean	裝置啟用狀態
provisioned	boolean	裝置佈建狀態
simulated	boolean	裝置模擬狀態
template	字串	裝置範本識別碼
scopes	字串	組織識別碼

篩選支援的函式：

目前，裝置清單唯一支援的篩選函式是 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 會識別裝置範本和要比對的任何屬性。 下列範例會建立裝置群組，其中包含與「dtmi:modelDefinition:dtdlv2」範本相關聯且 provisioned 屬性為 true 的所有裝置

{
  "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 應用程式。

建立註冊群組

X509

當您為使用 X.509 憑證的裝置建立註冊群組時，您必須先將根憑證或中繼憑證上傳至 IoT Central 應用程式。

產生根憑證和裝置憑證

在本節中，您會產生要將裝置連線到 IoT Central 所需的 X.509 憑證。

警告

這種產生 X.509 憑證的方式僅供測試使用。 若為生產環境，請使用官方的安全機制來產生憑證。

1. 瀏覽至您下載的適用於 Node.js 的 Microsoft Azure IoT SDK 中的憑證產生器指令碼。 安裝必要的套件：

   cd azure-iot-sdk-node/provisioning/tools
   npm install
   

2. 建立根憑證，然後執行指令碼來衍生裝置憑證：

   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

entry - 憑證的項目，可以是 primary 或 secondary

使用此要求將主要或次要 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="
        }
    ]
}

下一步

您現已了解如何使用 REST API 管理裝置，因此下一個建議步驟是如何使用 REST API 控制裝置。