자습서: REST API를 사용하여 Azure IoT Central 애플리케이션 관리

아티클
03/04/2024

이 자습서에서는 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가 권한 부여에 사용하는 전달자 토큰을 생성합니다.

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를 실행합니다.

Postman

이 자습서에서는 Postman을 사용하여 REST API 호출을 수행합니다. Postman을 다운로드하고 설치하지 않으려는 경우 온라인 버전을 사용할 수 있습니다. 무료 버전의 Postman을 사용하여 자습서의 모든 단계를 완료할 수 있습니다.

이 자습서에서는 단계를 완료하는 데 도움이 되는 몇 가지 스크립트가 포함된 미리 정의된 Postman 컬렉션을 사용합니다.

Postman Collection 가져오기

컬렉션을 가져오려면 Postman을 열고 가져오기를 선택합니다. 가져오기 대화 상자에서 링크를 선택하고 다음 URL에 붙여넣고 계속을 선택합니다.

이제 작업 영역에 IoT Central REST 자습서 컬렉션이 포함됩니다. 이 컬렉션에는 자습서에서 사용하는 모든 API가 포함됩니다.

컬렉션은 변수를 사용하여 REST API 호출을 매개 변수화합니다. 변수를 보려면 IoT Central REST 자습서 옆에 있는 ...를 선택하고 편집을 선택합니다. 변수를 선택합니다. 대부분의 변수는 API 호출을 수행할 때 자동으로 설정되거나 미리 설정된 값이 있습니다.

REST API에 권한을 부여합니다.

REST API를 사용하려면 먼저 권한 부여를 구성해야 합니다. 이 자습서의 REST API 호출은 다음 세 가지 권한 부여 유형 중 하나를 사용합니다.

https://management.azure.com에 대한 액세스 권한을 부여하는 전달자 토큰입니다. IoT Central 애플리케이션을 만들고 삭제할 때 이 전달자 토큰을 사용합니다. IoT Central 애플리케이션은 Azure 리소스입니다.
https://apps.azureiotcentral.com에 대한 액세스 권한을 부여하는 전달자 토큰입니다. 이 전달자 토큰을 사용하여 IoT Central 애플리케이션에서 API 토큰을 만듭니다.
IoT Central 애플리케이션의 기능에 대한 액세스 권한을 부여하는 관리자 및 운영자 API 토큰입니다. 이 자습서의 대부분의 API 호출에 이러한 토큰을 사용합니다. 이러한 토큰은 하나의 특정 IoT Central 애플리케이션에 대한 액세스 권한만 부여합니다.

Postman 컬렉션에서 다음 변수에 값을 할당합니다.

bearerToken: 다음 Azure CLI 명령을 실행하여 https://management.azure.com에 대한 액세스 권한을 부여하는 전달자 토큰을 생성합니다.
```
az login
az account get-access-token --resource https://management.azure.com
```
팁

Cloud Shell 사용하는 경우에도 az login을 실행해야 할 수 있습니다.

컬렉션 변수의 bearerToken에 대한 현재 값 열에 accessToken 값을 복사합니다.
bearerTokenApp: 다음 Azure CLI 명령을 실행하여 https://apps.azureiotcentral.com에 대한 액세스 권한을 부여하는 전달자 토큰을 생성합니다.
```
az account get-access-token --resource https://apps.azureiotcentral.com
```
팁

셸의 새 인스턴스를 시작한 경우 az login을 다시 실행합니다.

컬렉션 변수의 bearerTokenApp에 대한 현재 값 열에 accessToken 값을 복사합니다.
subscriptionId: 구독 ID가 이전 두 명령의 출력에 포함되었습니다. 컬렉션 변수의 subscriptionId에 대한 현재 값 열에 subscription 값을 복사합니다.

Screenshot that shows the variables set manually in the Postman collection.

변경 내용을 Postman 컬렉션에 저장해야 합니다.

참고 항목

전달자 토큰은 1시간 후에 만료됩니다.

애플리케이션 만들기

컨트롤 플레인 요청을 사용하여 IoT Central 애플리케이션을 만들고 관리할 수 있습니다. 다음 PUT 요청을 사용하여 이 자습서에서 사용하는 애플리케이션을 만듭니다. 요청은 전달자 토큰을 사용하여 권한을 부여하고 임의의 애플리케이션 이름을 생성합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 IoT 중앙 애플리케이션 만들기 요청을 선택합니다.
보내기를 선택합니다.
요청이 성공하는지 확인합니다. 실패하면 Postman 컬렉션에 bearerToken 및 subscriptionId 변수 값을 입력했는지 확인합니다.
시각화를 선택하여 새 IoT Central 애플리케이션의 URL을 확인합니다. 이 자습서의 뒷부분에서 필요하므로 네임스페이스 이름을 적어둡니다.

Screenshot that shows the Visualize tab with the application URL in Postman.

API 토큰 만들기

다음 데이터 평면 요청을 사용하여 IoT Central 애플리케이션에서 애플리케이션 API 토큰을 만듭니다. 이 자습서의 일부 요청에는 관리자 권한이 있는 API 토큰이 필요하지만 대부분은 연산자 권한을 사용할 수 있습니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 운영자 토큰 만들기 요청을 선택합니다.
보내기를 선택합니다.
Postman에서 IoT Central REST 자습서 컬렉션을 열고 관리자 토큰 만들기 요청을 선택합니다.
보내기를 선택합니다.

IoT 중앙 애플리케이션에서 이러한 토큰을 보려면 애플리케이션을 열고 보안 > 권한 > API 토큰으로 이동합니다.

참고 항목

Postman의 스크립트는 이러한 API 토큰을 컬렉션 변수 목록에 자동으로 추가합니다.

디바이스 등록

디바이스를 연결하려면 먼저 디바이스를 IoT Central에 등록해야 합니다. 다음 요청을 사용하여 애플리케이션에 디바이스를 등록하고 디바이스 자격 증명을 검색합니다. 첫 번째 요청은 디바이스 ID로 phone-001을 사용하여 디바이스를 만듭니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 디바이스 추가 요청을 선택합니다.
보내기를 선택합니다. 응답에서 디바이스가 프로비전되지 않은 것을 확인합니다.
Postman에서 IoT Central REST 자습서 컬렉션을 열고 디바이스 자격 증명 가져오기 요청을 선택합니다.
보내기를 선택합니다.
시각화 탭에는 디바이스가 연결할 수 있어야 하는 ID 범위 및 기본 키 값이 표시됩니다.

디바이스 프로비전 및 연결

스마트폰에서 디바이스 자격 증명을 수동으로 입력할 필요가 없도록 IoT Central에서 생성된 QR 코드를 사용할 수 있습니다. QR 코드는 디바이스 ID, ID 범위, 기본 키를 인코딩합니다. QR 코드를 표시하려면 다음을 수행합니다.

이전에 적어 두었던 애플리케이션 URL을 사용하여 IoT 중앙 애플리케이션을 엽니다.
IoT Central 애플리케이션에서 디바이스 > 내 휴대폰 앱 > 연결 > QR 코드로 이동합니다. 디바이스가 연결될 때까지 이 페이지를 열어 두세요.

Screenshot that shows the QR code you use to connect the device.

설정 간소화를 위해 이 문서에서는 IoT 플러그 앤 플레이 스마트폰 앱을 IoT 디바이스로 사용합니다. 앱은 스마트폰의 센서에서 수집된 원격 분석을 보내고, IoT Central에서 호출된 명령에 응답하고, 속성 값을 IoT Central에 보고합니다.

앱 스토어 중 하나에서 다음과 같이 스마트폰에 앱을 설치합니다.

IoT 플러그 앤 플레이 앱을 Iot Central 애플리케이션에 연결하려면 다음을 수행합니다.

스마트폰에서 IoT PnP 앱을 엽니다.
시작 페이지에서 QR 코드 스캔을 선택합니다. 스마트폰 카메라로 QR코드를 비추세요. 그런 다음, 연결이 설정되는 동안 몇 초 동안 기다립니다.
앱의 원격 분석 페이지에서 앱이 IoT Central로 보내는 데이터를 볼 수 있습니다. 로그 페이지에서 디바이스 연결 및 여러 초기화 메시지를 볼 수 있습니다.

이제 디바이스가 프로비전되었는지 확인하려면 REST API를 사용할 수 있습니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 디바이스 가져오기 요청을 선택합니다.
보내기를 선택합니다. 이제 응답에서 디바이스가 프로비전되지 않은 것을 확인합니다. 또한 IoT Central은 디바이스에서 보낸 모델 ID에 따라 디바이스 템플릿을 디바이스에 할당했습니다.

REST API를 사용하여 애플리케이션에서 디바이스 템플릿을 관리할 수 있습니다. 예를 들어 애플리케이션에서 디바이스 템플릿을 보려면 다음을 수행합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 디바이스 템플릿 가져오기 요청을 선택합니다.
보내기를 선택합니다.

디바이스를 쿼리하고 제어합니다.

REST API를 사용하여 디바이스에서 원격 분석을 쿼리할 수 있습니다. 다음 요청은 특정 디바이스 템플릿 ID를 공유하는 모든 디바이스에서 가속도계 데이터를 반환합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 쿼리 실행 요청을 선택합니다.
보내기를 선택합니다.

REST API를 사용하여 디바이스 속성을 읽고 설정할 수 있습니다. 다음 요청은 디바이스가 구현하는 디바이스 정보 구성 요소의 모든 속성 값을 반환합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 구성 요소 요청에서 속성 가져오기를 선택합니다.
보내기를 선택합니다.

REST API를 사용하여 디바이스 명령을 호출할 수 있습니다. 다음 요청은 3초 동안 스마트폰 표시등을 두 번 켜는 명령을 호출합니다. 명령을 실행하려면 스마트폰 화면이 IoT 플러그 앤 플레이 앱이 표시되어 있어야 합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 명령 호출 요청을 선택합니다.
보내기를 선택합니다.

원격 분석 내보내기

REST API를 사용하여 IoT Central 애플리케이션을 구성하고 관리할 수 있습니다. 다음 단계에서는 웹후크에 원격 분석 값을 보내도록 데이터 내보내기를 구성하는 방법을 보여 드립니다. 설정을 간소화하기 위해 이 문서에서는 RequestBin 웹후크를 대상으로 사용합니다. RequestBin 은 Microsoft가 아닌 서비스입니다.

데이터 내보내기 대상에 대한 테스트 엔드포인트를 만들려면 다음을 수행합니다.

RequestBin으로 이동합니다.
RequestBin 만들기를 선택합니다.
사용 가능한 방법 중 하나를 사용하여 로그인합니다.
RequestBin 엔드포인트의 URL을 복사합니다.
Postman에서 IoT Central REST 자습서 컬렉션을 열고 컬렉션 변수로 이동합니다.
RequestBin 엔드포인트의 URL을 컬렉션 변수의 webHookURL에 대한 현재 값 열에 붙여넣습니다.
변경 내용을 저장합니다.

REST API를 사용하여 IoT Central 애플리케이션에서 내보내기 대상을 구성하려면 다음을 수행합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 웹후크 내보내기 대상 만들기 요청을 선택합니다.
보내기를 선택합니다.

REST API를 사용하여 IoT Central 애플리케이션에서 내보내기 정의를 구성하려면 다음을 수행합니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 원격 분석 내보내기 대상 만들기 요청을 선택합니다.
보내기를 선택합니다. 상태가 시작되지 않음입니다.

내보내기를 시작하는 데 몇 분 정도 걸릴 수 있습니다. REST API를 사용하여 내보내기의 상태 검사:

Postman에서 IoT Central REST 자습서 컬렉션을 열고 ID로 내보내기 가져오기 요청을 선택합니다.
보내기를 선택합니다. 상태 정상이면 IoT Central이 웹후크에 원격 분석을 보냅니다.

화면이 켜져 있고 IoT 플러그 앤 플레이 앱이 표시되지 않는 한 스마트폰의 앱은 원격 분석을 보내지 않습니다.

스마트폰 앱이 원격 분석을 보내는 경우 RequestBin으로 이동하여 내보낸 원격 분석을 확인합니다.

리소스 정리

이 자습서에서 사용한 IoT Central 애플리케이션을 완료한 경우 REST API를 사용하여 삭제할 수 있습니다.

Postman에서 IoT Central REST 자습서 컬렉션을 열고 IoT 중앙 애플리케이션 삭제 요청을 선택합니다.
보내기를 선택합니다.

팁

이 요청은 자습서 시작 시 생성한 전달자 토큰을 사용합니다. 전달자 토큰은 1시간 후에 만료됩니다. https://apps.azureiotcentral.com에 대한 액세스 권한을 부여하는 새 전달자 토큰을 생성해야 할 수 있습니다.

다음 단계

IoT Central 자습서 세트를 계속 진행하고 IoT Central 솔루션 빌드에 대해 자세히 알아보려면 다음을 참조하세요.

게이트웨이 디바이스 템플릿 만들기