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

아티클
05/27/2023

IoT Central REST API를 사용하면 IoT Central 애플리케이션과 통합되는 클라이언트 애플리케이션을 개발할 수 있습니다. REST API를 사용하여 IoT Central 애플리케이션에서 디바이스를 쿼리할 수 있습니다. 쿼리 REST API를 사용하는 방법의 예는 다음과 같습니다.

디바이스에서 보고한 마지막 10개의 원격 분석 값을 가져옵니다.
오류 상태이고 오래된 펌웨어가 있는 모든 디바이스를 찾습니다.
10분 기간의 평균적인 디바이스의 원격 분석 추세입니다.
모든 자동 온도 조절기 디바이스의 현재 펌웨어 버전을 가져옵니다.

이 문서에서는 /query 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를 사용하여 디바이스를 쿼리하는 방법을 알아보려면 데이터 탐색기를 사용하여 디바이스 데이터를 분석하는 방법을 참조하세요.

쿼리 실행

다음 요청을 사용하여 쿼리를 실행합니다.

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

쿼리는 요청 본문에 있으며 다음 예제와 같습니다.

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

FROM 절의 dtmi:eclipsethreadx:devkit:hlby5jgib2o 값은 디바이스 템플릿 ID입니다. 디바이스 템플릿 ID를 찾으려면 IoT Central 애플리케이션의 디바이스 페이지로 이동하여 마우스로 템플릿을 사용하는 디바이스 위를 가리킵니다. 카드에 디바이스 템플릿 ID가 포함되어 있습니다.

페이지 URL에서 디바이스 템플릿 ID를 찾는 방법을 보여 주는 스크린샷

응답에는 동일한 디바이스 템플릿을 공유하는 여러 디바이스의 원격 분석이 포함됩니다. 이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

구문

쿼리 구문은 SQL 구문과 비슷하며 다음 절로 구성됩니다.

SELECT는 필수이며, 디바이스 원격 분석 값과 같이 검색하려는 데이터를 정의합니다.
FROM은 필수이며, 쿼리하는 디바이스 유형을 식별합니다. 이 절은 디바이스 템플릿 ID를 지정합니다.
WHERE는 선택 사항이며, 결과를 필터링할 수 있습니다.
ORDER BY는 선택 사항이며, 결과를 정렬할 수 있습니다.
GROUP BY는 선택 사항이며, 결과를 집계할 수 있습니다.

다음 섹션에서는 이러한 절에 대해 자세히 설명합니다.

SELECT 절

SELECT 절은 쿼리 출력에 포함할 데이터 값을 나열하며 다음 항목을 포함할 수 있습니다.

원격 분석. 디바이스 템플릿의 원격 분석 이름을 사용합니다.
$id. 디바이스 ID
$provisioned. 디바이스가 이미 프로비전되었는지 여부를 나타내는 부울 값입니다.
$simulated. 디바이스가 시뮬레이션된 디바이스인지 여부를 나타내는 부울 값입니다.
$ts. 원격 분석 값과 연결된 타임스탬프입니다.

디바이스 템플릿에서 구성 요소를 사용하는 경우 다음과 같이 구성 요소에 정의된 원격 분석을 참조합니다.

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

디바이스 템플릿에서 구성 요소 이름을 확인할 수 있습니다.

SELECT 절에 적용되는 제한 사항은 다음과 같습니다.

와일드카드 연산자가 없습니다.
선택 목록에는 15개를 초과하는 항목이 있을 수 없습니다.
쿼리는 최대 10,000개의 레코드를 반환합니다.

별칭

AS 키워드를 사용하여 SELECT 절에서 항목에 대한 별칭을 정의합니다. 별칭은 쿼리 출력에서 사용됩니다. 쿼리의 다른 위치에서도 사용할 수 있습니다. 예시:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

팁

선택 목록의 다른 항목을 별칭으로 사용할 수 없습니다. 예를 들어 SELECT id, temp AS id...는 허용되지 않습니다.

결과는 다음 출력과 같습니다.

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

TOP를 사용하여 쿼리에서 반환하는 결과의 수를 제한합니다. 예를 들어 다음 쿼리는 처음 10개의 결과를 반환합니다.

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

TOP를 사용하지 않는 경우 쿼리는 최대 10,000개의 결과를 반환합니다.

TOP에서 결과 수를 제한하기 전에 결과를 정렬하려면 ORDER BY를 사용합니다.

FROM 절

FROM 절은 디바이스 템플릿 ID를 포함해야 합니다. FROM 절은 쿼리하는 디바이스 유형을 지정합니다.

디바이스 템플릿 ID를 찾으려면 IoT Central 애플리케이션의 디바이스 페이지로 이동하여 마우스로 템플릿을 사용하는 디바이스 위를 가리킵니다. 카드에 디바이스 템플릿 ID가 포함되어 있습니다.

디바이스 - Get REST API 호출을 사용하여 디바이스에 대한 디바이스 템플릿 ID를 가져올 수도 있습니다.

WHERE 절

WHERE 절을 사용하면 값과 시간 범위를 사용하여 결과를 필터링할 수 있습니다.

기간

애플리케이션에서 원격 분석을 지정된 기간 내에 받으려면 WHERE 절의 일부로 WITHIN_WINDOW를 사용합니다. 예를 들어 마지막 날의 온도 및 습도 원격 분석을 검색하려면 다음 쿼리를 사용합니다.

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

시간 범위 값은 ISO 8601 기간 형식을 사용합니다. 다음 표에는 몇 가지 예가 포함되어 있습니다.

예제	설명
PT10M	지난 10분
P1D	전날
P2DT12H	지난 2일 12시간
P1W	지난 주
PT5H	지난 5시간
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z'	특정 시간 범위

값 비교

특정 값을 기반으로 원격 분석을 가져올 수 있습니다. 예를 들어 다음 쿼리에서는 온도가 0보다 높고, 압력이 50보다 높고, 디바이스 ID가 sample-002 및 sample-003 중 하나인 모든 메시지를 반환합니다.

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

다음과 같은 연산자가 지원됩니다.

AND 및 OR 논리 연산자
=, !=, >, <, >=, <=, <> 및 IN 비교 연산자

참고 항목

IN 연산자는 원격 분석 및 $id에서만 작동합니다.

WHERE 절에 적용되는 제한 사항은 다음과 같습니다.

단일 쿼리에서 최대 10개의 연산자를 사용할 수 있습니다.
쿼리에서 WHERE 절은 원격 분석 및 디바이스 메타데이터 필터만 포함할 수 있습니다.
쿼리에서 최대 10,000개의 레코드를 검색할 수 있습니다.

집계 및 GROUP BY 절

집계 함수를 사용하면 시간 범위 내의 원격 분석 데이터에 대한 평균, 최댓값 및 최솟값과 같은 값을 계산할 수 있습니다. 예를 들어 다음 쿼리에서는 10분 기간 동안 sample-001 디바이스의 평균 온도 및 습도를 계산합니다.

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

결과는 다음 출력과 같습니다.

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

지원되는 집계 함수는 SUM, MAX, MIN, COUNT, AVG, FIRST 및 LAST입니다.

GROUP BY WINDOW를 사용하여 창 크기를 지정합니다. GROUP BY WINDOW를 사용하지 않는 경우 쿼리는 지난 30일 동안의 원격 분석을 집계합니다.

참고 항목

원격 분석 값만 집계할 수 있습니다.

ORDER BY 절

ORDER BY 절을 사용하면 원격 분석 값, 타임스탬프 또는 디바이스 ID를 기준으로 쿼리 결과를 정렬할 수 있습니다. 오름차순 또는 내림차순으로 정렬할 수 있습니다. 예를 들어 다음 쿼리에서는 가장 최근의 결과를 먼저 반환합니다.

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

팁

정렬 후에 쿼리에서 반환하는 결과 수를 제한하려면 ORDER BY를 TOP와 결합합니다.

제한

쿼리에 대한 현재 제한 사항은 다음과 같습니다.

SELECT 절 목록의 항목 수는 15개 이하입니다.
WHERE 절의 논리 연산 수는 10개 이하입니다.
쿼리 문자열의 최대 길이는 350자입니다.
SELECT 절 목록에는 와일드카드(*)를 사용할 수 없습니다.
쿼리는 최대 10,000개의 레코드를 검색할 수 있습니다.

다음 단계

이제 REST API를 사용하여 디바이스를 쿼리하는 방법을 알아보았으므로 제안되는 다음 단계에서는 IoT Central REST API를 사용하여 사용자 및 역할을 관리하는 방법을 알아봅니다.

다음을 통해 공유