IoT Central REST API를 사용하여 디바이스를 관리하는 방법

  • 아티클

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 참조를 참조하세요.

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 가져오기
승인을 기다리는 중 디바이스 연결 그룹에서 자동 승인 옵션을 사용할 수 없으며 디바이스가 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를 사용합니다. 다음 표에는 사용할 수 있는 비교 연산자가 나와 있습니다.

비교 연산자 기호 예시
같음 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
또는 또는 id eq 'device1' or simulated eq false

현재 filter는 다음 디바이스 필드에서 작동합니다.

FieldName Type 설명
id string 디바이스 ID
displayName string 디바이스 표시 이름
enabled 부울 값 디바이스 사용 상태
provisioned 부울 값 디바이스 프로비전 상태
simulated 부울 값 디바이스 시뮬레이션 상태
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는 디바이스 템플릿과 일치하는 모든 속성을 식별합니다. 다음 예제에서는 속성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.

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "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 인증서를 생성합니다.

Warning

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

    팁

    디바이스 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인 등록 그룹의 세부 정보를 검색합니다.

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