자습서: REST API를 사용하여 Azure IoT Central 애플리케이션 관리
이 자습서에서는 Azure IoT Central REST API를 사용하여 IoT Central 애플리케이션을 만들고 상호 작용하는 방법을 보여 줍니다. 이 자습서에서는 REST API를 사용하여 빠른 시작에서 웹 UI를 사용하여 완료한 많은 단계를 완료합니다. 이러한 단계에는 스마트폰에서 앱을 IoT Central에 연결하는 IoT 디바이스로 사용하는 것이 포함됩니다.
이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.
- REST API에 권한을 부여합니다.
- IoT Central 애플리케이션을 만듭니다.
- 애플리케이션에 디바이스 추가
- 디바이스를 쿼리하고 제어합니다.
- 데이터 내보내기 설정
- 애플리케이션을 삭제합니다.
필수 조건
이 자습서를 완료하려면 다음이 필요합니다.
활성화된 Azure 구독. Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
공식 앱 스토어 중 하나에서 무료 앱을 설치할 수 있는 Android 또는 iOS 휴대폰.
Azure CLI
Azure CLI를 사용하여 REST API를 호출하고 일부 REST API가 권한 부여에 사용하는 전달자 토큰을 생성합니다.
Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.
메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.
az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.
REST API에 권한을 부여합니다.
REST API를 사용하려면 먼저 권한 부여를 구성해야 합니다. 이 자습서의 REST API 호출은 다음 두 가지 권한 부여 유형 중 하나를 사용합니다.
https://apps.azureiotcentral.com에 대한 액세스 권한을 부여하는 전달자 토큰입니다. 이 전달자 토큰을 사용하여 IoT Central 애플리케이션에서 API 토큰을 만듭니다.- IoT Central 애플리케이션의 기능에 대한 액세스 권한을 부여하는 관리자 및 운영자 API 토큰입니다. 이 자습서의 대부분의 API 호출에 이러한 토큰을 사용합니다. 이러한 토큰은 하나의 특정 IoT Central 애플리케이션에 대한 액세스 권한만 부여합니다.
다음 Azure CLI 명령을 실행하여 다음에 대한 액세스 권한을 부여하는 전달자 토큰을 생성합니다 https://apps.azureiotcentral.com.
az account get-access-token --resource https://apps.azureiotcentral.com
팁
셸의 새 인스턴스를 시작한 경우 az login을 다시 실행합니다.
값을 적어 accessToken 두세요. 자습서의 뒷부분에서 사용합니다.
참고 항목
전달자 토큰은 1시간 후에 만료됩니다. 만료되는 경우 동일한 명령을 실행하여 새 전달자 토큰을 생성합니다.
리소스 그룹 만들기
Azure cli를 사용하여 이 자습서에서 만든 IoT Central 애플리케이션이 포함된 리소스 그룹을 만듭니다.
az group create --name iot-central-rest-tutorial --location eastus
IoT Central 애플리케이션 만들기
다음 명령을 사용하여 이 자습서에서 사용할 임의 이름으로 IoT Central 애플리케이션을 생성합니다.
appName=app-rest-$(date +%s)
az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName
애플리케이션 이름을 기록해 두세요. 이 자습서의 뒷부분에서 사용합니다.
API 토큰 만들기
다음 데이터 평면 요청을 사용하여 IoT Central 애플리케이션에서 애플리케이션 API 토큰을 만듭니다. 이 자습서의 일부 요청에는 관리자 권한이 있는 API 토큰이 필요하지만 대부분은 연산자 권한을 사용할 수 있습니다.
Azure CLI를 사용하여 호출 operator-token 되는 연산자 토큰을 만들려면 다음 명령을 실행합니다. 역할 GUID는 모든 IoT Central 애플리케이션에서 운영자 역할의 ID입니다.
appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>
az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'
명령이 반환하는 연산자 토큰을 기록해 두세요. 자습서의 뒷부분에서 사용합니다. 토큰은 다음과 같습니다 SharedAccessSignature sr=2....
Azure CLI를 사용하여 호출 admin-token 된 관리자 토큰을 만들려면 다음 명령을 실행합니다. 역할 GUID는 모든 IoT Central 애플리케이션에서 관리자 역할의 ID입니다.
$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>
az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'
명령이 반환하는 관리자 토큰을 기록해 두세요. 자습서의 뒷부분에서 사용합니다. 토큰은 다음과 같습니다 SharedAccessSignature sr=2....
IoT 중앙 애플리케이션에서 이러한 토큰을 보려면 애플리케이션을 열고 보안 > 권한 > API 토큰으로 이동합니다.
디바이스 등록
디바이스를 연결하려면 먼저 디바이스를 IoT Central에 등록해야 합니다. 다음 요청을 사용하여 애플리케이션에 디바이스를 등록하고 디바이스 자격 증명을 검색합니다. 첫 번째 요청은 디바이스 ID로 phone-001을 사용하여 디바이스를 만듭니다.
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'
az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
명령이 반환하는 idScope 값과 primaryKey 값을 기록해 두세요. 자습서의 뒷부분에서 사용합니다.
디바이스 프로비전 및 연결
스마트폰에서 디바이스 자격 증명을 수동으로 입력할 필요가 없도록 IoT Central에서 생성된 QR 코드를 사용할 수 있습니다. QR 코드는 디바이스 ID, ID 범위, 기본 키를 인코딩합니다. QR 코드를 표시하려면 다음을 수행합니다.
- 이전에 적어 두었던 애플리케이션 URL을 사용하여 IoT 중앙 애플리케이션을 엽니다.
- IoT Central 애플리케이션에서 디바이스 > 내 휴대폰 앱 > 연결 > QR 코드로 이동합니다. 디바이스가 연결될 때까지 이 페이지를 열어 두세요.
설정 간소화를 위해 이 문서에서는 IoT 플러그 앤 플레이 스마트폰 앱을 IoT 디바이스로 사용합니다. 앱은 스마트폰의 센서에서 수집된 원격 분석을 보내고, IoT Central에서 호출된 명령에 응답하고, 속성 값을 IoT Central에 보고합니다.
앱 스토어 중 하나에서 다음과 같이 스마트폰에 앱을 설치합니다.
IoT 플러그 앤 플레이 앱을 Iot Central 애플리케이션에 연결하려면 다음을 수행합니다.
스마트폰에서 IoT PnP 앱을 엽니다.
시작 페이지에서 QR 코드 스캔을 선택합니다. 스마트폰 카메라로 QR코드를 비추세요. 그런 다음, 연결이 설정되는 동안 몇 초 동안 기다립니다.
앱의 원격 분석 페이지에서 앱이 IoT Central로 보내는 데이터를 볼 수 있습니다. 로그 페이지에서 디바이스 연결 및 여러 초기화 메시지를 볼 수 있습니다.
이제 디바이스가 프로비전되었는지 확인하려면 REST API를 사용할 수 있습니다.
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
명령이 반환하는 template 값을 기록해 두세요. 자습서의 뒷부분에서 사용합니다.
REST API를 사용하여 애플리케이션에서 디바이스 템플릿을 관리할 수 있습니다. 예를 들어 애플리케이션에서 디바이스 템플릿을 보려면 다음을 수행합니다.
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
디바이스를 쿼리하고 제어합니다.
REST API를 사용하여 디바이스에서 원격 분석을 쿼리할 수 있습니다. 다음 요청은 특정 디바이스 템플릿 ID를 공유하는 모든 디바이스에서 가속도계 데이터를 반환합니다.
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query
az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"
REST API를 사용하여 디바이스 속성을 읽고 설정할 수 있습니다. 다음 요청은 디바이스가 구현하는 디바이스 정보 구성 요소의 모든 속성 값을 반환합니다.
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
REST API를 사용하여 디바이스 명령을 호출할 수 있습니다. 다음 요청은 3초 동안 스마트폰 표시등을 두 번 켜는 명령을 호출합니다. 명령을 실행하려면 스마트폰 화면이 IoT 플러그 앤 플레이 앱이 표시되어 있어야 합니다.
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'
리소스 정리
이 자습서에서 사용한 IoT Central 애플리케이션을 완료한 경우 삭제할 수 있습니다.
appName=<the app name generated previously>
az iot central app delete --name $appName --resource-group iot-central-rest-tutorial