IoT Central REST API を使用してデバイスを管理する方法

[アーティクル]
03/01/2024

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。 RREST 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 アプリケーションでデバイスを個別に管理する」を参照してください。

Devices REST API

IoT Central REST API を使用すると、次のことができます。

アプリケーションにデバイスを追加する
アプリケーションでデバイスを更新する
アプリケーションでデバイスの一覧を取得します
ID でデバイスを取得する
デバイスの資格情報を取得する
アプリケーション内のデバイスを削除する
アプリケーション内のデバイスの一覧をフィルター処理する

デバイスを追加する

新しいデバイスを作成するには、次の要求を使用します。

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

次の例では、デバイステンプレートのデバイスを追加する要求本文を示しています。 template 詳細は、IoT Central アプリケーション UI の [デバイステンプレート] ページから取得できます。

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

Note

デバイスをマウスでポイントすると、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`
Registered	デバイスが自動または手動で承認されました。	`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 を使用して、デバイスの一覧をフィルター処理する式を作成します。次の表は、使用できる比較演算子を示しています。

比較演算子	記号	例
[等しい]	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	or	`id eq 'device1' or simulated eq false`

現時点では、filter は次のデバイスフィールドで機能します。

FieldName	型	説明
`id`	string	Device 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
        }
    ]
}

また、2 つ以上のフィルターを組み合わせることもできます。

次の例は、表示名に文字列 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: デバイスグループの簡単な概要。

organizations フィールドは、アプリケーションで組織階層が定義されている場合にのみ使います。組織について詳しくは、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 証明書を使用するデバイスを Azure IoT Central アプリケーションに接続する方法」を参照してください。

X.509 証明書を使用するデバイスの登録グループを作成する場合は、最初にルート証明書または中間証明書を IoT Central アプリケーションにアップロードする必要があります。

ルート証明書とデバイス証明書を生成する

このセクションでは、デバイスを IoT Central に接続するために必要な X.509 証明書を生成します。

警告

この X.509 証明書の生成方法は、テストのみを目的としています。運用環境では、証明書を生成するためのセキュリティで保護された正式なメカニズムを使用する必要があります。

ダウンロードした Microsoft Azure IoT SDK for Node.js で、証明書生成スクリプトがある場所に移動します。必要なパッケージをインストールします。
```
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 を使用してデバイスを管理する方法

Devices REST API

デバイスを追加する

デバイスの取得

デバイスの資格情報の取得

デバイスを更新する

デバイスを削除する

デバイスを一覧表示

配置マニフェストを割り当てる

ODATA フィルターを使用する

maxpagesize

フィルター

orderby

デバイス グループ

デバイス グループを追加する

デバイス グループを取得する

デバイス グループを更新する

デバイス グループの削除

デバイス グループの一覧を取得

登録グループ

登録グループを作成する

ルート証明書とデバイス証明書を生成する

Base-64 エンコード バージョンのルート証明書を生成する

X.509 登録グループを追加する

登録グループに X.509 証明書を追加する

X.509 証明書の確認コードを生成する

検証証明書を生成する

登録グループの X.509 証明書を検証する

登録グループの X.509 証明書を取得する

登録グループから X.509 証明書を削除する

登録グループを取得する

登録グループを更新する

登録グループを削除する

登録グループのリストを取得する

その他のリソース

デバイスグループ

デバイスグループを追加する

デバイスグループを取得する

デバイスグループを更新する

デバイスグループの削除

デバイスグループの一覧を取得

Base-64 エンコードバージョンのルート証明書を生成する