IoT Central REST API를 사용하여 작업을 만들고 관리하는 방법

아티클
10/22/2024

IoT Central REST API를 사용하면 IoT Central 애플리케이션과 통합되는 클라이언트 애플리케이션을 개발할 수 있습니다. REST API를 사용하여 IoT Central 애플리케이션에서 작업을 만들고 관리할 수 있습니다. REST API를 사용하면 다음을 수행할 수 있습니다.

응용 프로그램에서 작업을 나열하고 작업 세부 정보를 봅니다.
애플리케이션에서 작업 만들기 및 실행
애플리케이션에서 작업을 중지, 다시 시작 및 다시 실행합니다.
작업을 예약하고 애플리케이션에서 예약된 작업 세부 정보를 봅니다.

예약된 작업은 나중에 실행되도록 만들어집니다. 예약된 작업이 일회성, 매일 또는 매주 실행되도록 시작 날짜 및 시간을 설정할 수 있습니다. 예약되지 않은 작업은 한 번만 실행됩니다.

이 문서에서는 /jobs/{job_id} API를 사용하여 기기를 일괄 제어하는 방법을 설명합니다. 디바이스를 개별적으로 제어할 수도 있습니다.

모든 IoT Central REST API 호출에는 권한 부여 헤더가 필요합니다. 자세히 알아보려면 IoT Central REST API 호출을 인증하고 권한을 부여하는 방법을 참조하세요.

IoT Central REST API에 대한 참조 설명서는 Azure IoT Central REST API 참조를 참조하세요.

UI에서 작업을 만들고 관리하는 방법을 알아보려면 Azure IoT Central 애플리케이션에서 대량으로 디바이스 관리를 참조하세요.

작업 페이로드

이 문서에서 설명하는 대부분의 API에는 다음 JSON 조각과 같은 정의가 포함되어 있습니다.

{
  "id": "job-014",
  "displayName": "Set target temperature",
  "description": "Set target temperature for all thermostat devices",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "56"
    }
  ],
  "status": "complete"
}

다음 표에서는 이전 JSON 조각의 필드에 대해 설명합니다.

필드	설명
`id`	애플리케이션의 작업에 대한 고유 ID입니다.
`displayName`	애플리케이션에서 작업의 표시 이름입니다.
`description`	작업에 대한 설명입니다.
`group`	작업이 적용되는 디바이스 그룹의 ID입니다. `deviceGroups` 미리보기 REST API를 사용하여 애플리케이션의 기기 그룹 목록을 가져옵니다.
`status`	작업의 상태. `complete`, `cancelled`, `failed`, `pending`, `running`, `stopped` 중 하나입니다.
`batch`	있는 경우 이 섹션은 작업에서 기기를 일괄 처리하는 방법을 정의합니다.
`batch/type`	각 배치의 크기는 그룹에 있는 총 기기의 `percentage` 또는 기기의 `number`입니다.
`batch/value`	장치의 백분율 또는 각 배치의 장치 수입니다.
`cancellationThreshold`	있는 경우 이 섹션은 작업에 대한 취소 임계값을 정의합니다.
`cancellationThreshold/batch`	`true` 또는 `false`. true인 경우 각 배치에 대해 취소 임계값이 설정됩니다. `false`인 경우 취소 임계값이 전체 작업에 적용됩니다.
`cancellationThreshold/type`	작업의 취소 임계값은 기기의 `percentage` 또는 `number`입니다.
`cancellationThreshold/value`	취소 임계값을 정의하는 장치의 백분율 또는 장치 수입니다.
`data`	작업이 수행하는 작업의 배열입니다.
`data/type`	`PropertyJobData`, `CommandJobData`, `CloudPropertyJobData` 또는 `DeviceTemplateMigrationJobData` 중 하나입니다. API의 미리 보기 버전에는 `DeviceManifestMigrationJobData`가 포함됩니다.
`data/target`	대상 장치의 모델 ID입니다.
`data/path`	속성, 명령 또는 클라우드 속성의 이름입니다.
`data/value`	설정할 속성 값 또는 보낼 명령 매개 변수입니다.

작업 정보 얻기

다음 요청을 사용하여 애플리케이션의 작업 목록을 검색합니다.

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

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

{
  "value": [
    {
      "id": "job-006",
      "displayName": "Set customer name",
      "description": "Set the customer name cloud property",
      "group": "4fcbec3b-5ee8-4324-855d-0f03b56bcf7f",
      "data": [
        {
          "type": "CloudPropertyJobData",
          "target": "dtmi:modelDefinition:bojo9tfju:yfvu5gv2vl",
          "path": "CustomerName",
          "value": "Contoso"
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-005",
      "displayName": "Set target temperature",
      "description": "Set target temperature device property",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "data": [
        {
          "type": "PropertyJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "targetTemperature",
          "value": 56
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-004",
      "displayName": "Run device report",
      "description": "Call command to run the device reports",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "batch": {
        "type": "percentage",
        "value": 25
      },
      "cancellationThreshold": {
        "type": "percentage",
        "value": 10,
        "batch": false
      },
      "data": [
        {
          "type": "CommandJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "getMaxMinReport",
          "value": "2021-06-15T05:00:00.000Z"
        }
      ],
      "status": "complete"
    }
  ]
}

다음 요청을 사용하여 ID별로 개별 작업을 검색합니다.

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

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

{
  "id": "job-004",
  "displayName": "Run device report",
  "description": "Call command to run the device reports",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "CommandJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "getMaxMinReport",
      "value": "2021-06-15T05:00:00.000Z"
    }
  ],
  "status": "complete"
}

다음 요청을 사용하여 작업에서 장치의 세부 정보를 검색합니다.

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

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

{
  "value": [
    {
      "id": "therm-01",
      "status": "completed"
    },
    {
      "id": "therm-02",
      "status": "completed"
    },
    {
      "id": "therm-03",
      "status": "completed"
    },
    {
      "id": "therm-04",
      "status": "completed"
    }
  ]
}

작업 만들기

다음 요청을 사용하여 작업을 만듭니다.

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

요청 본문의 group 필드는 IoT Central 애플리케이션의 디바이스 그룹을 식별합니다. 작업은 디바이스 그룹을 사용하여 작업이 작동하는 디바이스 집합을 식별합니다.

적절한 디바이스 그룹이 아직 없는 경우 REST API 호출을 사용하여 만들 수 있습니다. 다음 예제에서는 group1을 그룹 ID로 사용하여 디바이스 그룹을 만듭니다.

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

디바이스 그룹을 만들 때 그룹에 포함할 디바이스를 선택하는 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"
}

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

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

이제 응답의 id 값을 사용하여 새 작업을 만들 수 있습니다.

{
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ]
}

이 요청에 대한 응답은 다음 예제와 같습니다. 초기 작업 상태는 pending입니다.

{
  "id": "job-006",
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ],
  "status": "pending"
}

작업 중지, 다시 시작 및 다시 실행

다음 요청을 사용하여 실행 중인 작업을 중지합니다.

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/stop?api-version=2022-07-31

요청이 성공하면 204 - No Content 응답을 반환합니다.

중지된 작업을 재개하려면 다음 요청을 사용하십시오.

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/resume?api-version=2022-07-31

요청이 성공하면 204 - No Content 응답을 반환합니다.

실패한 장치에서 기존 작업을 다시 실행하려면 다음 명령을 사용하십시오.

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/rerun/rerun-001?api-version=2022-07-31

예약된 작업 만들기

예약된 작업에 대한 페이로드는 표준 작업과 유사하지만 다음과 같은 추가 필드를 포함합니다.

필드	설명
일정/시작	작업의 시작 날짜 및 시간이며, ISO 8601 형식입니다.
일정/되풀이	`daily`, `monthly`, `yearly \|` 중 하나입니다.
일정/끝	작업에 대한 발생 횟수 또는 ISO 8601 형식의 종료 날짜를 지정하는 선택적 필드입니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

다음 예제에서는 예약된 작업을 만드는 요청 본문을 보여 줍니다.

{
    "displayName": "New Scheduled Job",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    }
}

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

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

예약된 작업 가져오기

다음 요청을 사용하여 예약된 작업을 가져옵니다.

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

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

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

예약된 작업 나열

다음 요청을 사용하여 예약된 작업 목록을 가져옵니다.

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

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

{
    "value": [
        {
            "id": "scheduled-Job-001",
            "displayName": "New Scheduled Job",
            "description": "",
            "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
                    "path": "Company",
                    "value": "Contoso"
                }
            ],
            "schedule": {
                "start": "2022-10-24T22:29:01Z",
                "recurrence": "daily"
            },
            "enabled": false,
            "completed": false,
            "etag": "\"88003877-0000-0700-0000-631020670000\""
        },
        {
            "id": "46480dff-dc22-4542-924e-a5d45bf347aa",
            "displayName": "test",
            "description": "",
            "group": "cdd04344-bb55-425b-a55a-954d68383289",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:rigado:evxfmi0xim",
                    "path": "test",
                    "value": 2
                }
            ],
            "schedule": {
                "start": "2022-09-01T03:00:00.000Z"
            },
            "enabled": true,
            "completed": true,
            "etag": "\"88000f76-0000-0700-0000-631020310000\""
        }
    ]
}

예약된 작업 업데이트

다음 요청을 사용하여 예약된 작업을 업데이트합니다.

PATCH https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

다음 예제에서는 예약된 작업을 업데이트하는 요청 본문을 보여 줍니다.

{
  "schedule": {
    "start": "2022-10-24T22:29:01Z",
    "recurrence": "weekly"
  }
}

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

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "weekly"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

예약된 작업 삭제

다음 요청을 사용하여 예약된 작업을 삭제합니다.

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

다음 단계

이제 REST API를 사용하여 작업을 관리하는 방법을 배웠으므로 제안된 다음 단계는 자습서: REST API를 사용하여 Azure IoT Central 애플리케이션을 관리하는 방법을 배우는 것입니다.

다음을 통해 공유

IoT Central REST API를 사용하여 작업을 만들고 관리하는 방법

작업 페이로드

작업 정보 얻기

작업 만들기

작업 중지, 다시 시작 및 다시 실행

예약된 작업 만들기

예약된 작업 가져오기

예약된 작업 나열

예약된 작업 업데이트

예약된 작업 삭제

다음 단계

피드백

추가 리소스