디바이스 쌍 시작(Azure CLI)
디바이스 쌍은 메타데이터, 구성, 조건을 비롯한 디바이스 상태 정보를 저장하는 JSON 문서입니다. IoT Hub는 여기에 연결하는 각 디바이스에 대해 하나의 디바이스 쌍을 유지합니다.
참고 항목
이 문서에서 설명하는 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.
디바이스 쌍의 용도:
솔루션 백 엔드의 디바이스 메타데이터를 저장합니다.
디바이스 앱의 사용 가능한 기능 및 상태(예: 사용된 연결 방법)와 같은 현재 상태 정보를 보고합니다.
디바이스 앱과 백 엔드 앱 간에 장기 실행 워크플로(예: 펌웨어 및 구성 업데이트)의 상태를 동기화합니다.
디바이스 메타데이터, 구성 또는 상태를 쿼리합니다.
디바이스 쌍은 디바이스 구성 및 상태를 동기화하고 쿼리하기 위해 설계되었습니다. 디바이스 쌍을 사용하는 경우를 포함한 디바이스 쌍에 대한 자세한 내용은 디바이스 쌍 이해를 참조하세요.
IoT 허브는 다음 요소를 포함하는 디바이스 쌍을 저장합니다.
태그. 솔루션 백 엔드만 액세스할 수 있는 디바이스 메타데이터입니다.
desired 속성. 솔루션 백 엔드에서 수정할 수 있고 디바이스 앱에서 관찰할 수 있는 JSON 개체입니다.
reported 속성. 디바이스 앱에서 수정할 수 있고 솔루션 백 엔드에서 읽을 수 있는 JSON 개체입니다.
태그 및 속성은 배열을 포함할 수 없지만 중첩된 개체를 포함할 수 있습니다.
다음 그림은 디바이스 쌍 조직을 보여 줍니다.
또한 솔루션 백 엔드는 위의 모든 데이터를 기반으로 하는 디바이스 쌍을 쿼리할 수 있습니다. 디바이스 쌍에 대한 자세한 내용은 디바이스 쌍 이해를 참조하세요. 쿼리에 대한 자세한 내용은 IoT Hub 쿼리 언어를 참조하세요.
이 문서는 다음을 수행하는 방법을 보여줍니다.
시뮬레이션된 디바이스를 사용하여 해당 연결 채널을 디바이스 쌍의 reported 속성으로 보고합니다.
이전에 만든 태그 및 속성에 필터를 사용하여 디바이스를 쿼리합니다.
디바이스 쌍 reported 속성을 사용하는 방법에 대한 자세한 내용은 디바이스-클라우드 통신 지침을 참조하세요.
이 문서에서는 두 개의 Azure CLI 세션을 만드는 방법을 보여 줍니다.
시뮬레이션된 디바이스를 만드는 세션. 시뮬레이션된 디바이스는 초기화될 때 디바이스의 해당 디바이스 쌍에서 해당 연결 채널을 reported 속성으로 보고합니다.
시뮬레이션된 디바이스에 대한 디바이스 쌍의 태그를 업데이트한 다음, IoT Hub에서 디바이스를 쿼리하는 세션. 쿼리는 두 세션에서 이전에 업데이트된 태그 및 속성에 따라 필터를 사용합니다.
필수 조건
Azure CLI 브라우저 또는 Windows 터미널과 같은 앱에서 실행되는 대화형 CLI 셸인 Azure Cloud Shell을 사용하여 이 문서의 명령을 실행할 수도 있습니다. Cloud Shell을 사용하는 경우에는 아무 것도 설치할 필요가 없습니다. 이 문서에 따라 CLI를 로컬에서 설치하여 사용하려면 Azure CLI 버전 2.36 이상이 필요합니다.
az --version을 실행하여 버전을 찾습니다. Azure CLI를 로컬로 설치하거나 업그레이드하려면 Azure CLI 설치를 참조하세요.IoT 허브. CLI 또는 Azure Portal을 사용하여 만듭니다.
방화벽에서 포트 8883이 열려 있는지 확인합니다. 이 문서의 샘플은 포트 8883을 통해 통신하는 MQTT 프로토콜을 사용합니다. 이 포트는 일부 회사 및 교육용 네트워크 환경에서 차단될 수 있습니다. 이 문제를 해결하는 자세한 내용과 방법은 IoT Hub에 연결(MQTT)을 참조하세요.
Cloud Shell 준비
Azure Cloud Shell을 사용하려면 먼저 이를 시작하고 구성해야 합니다. CLI를 로컬로 사용하는 경우 두 CLI 세션 준비 섹션으로 건너뜁니다.
Azure Portal의 페이지 머리글에서 Cloud Shell 아이콘을 선택합니다.
참고 항목
Cloud Shell을 처음 사용하는 경우 Cloud Shell을 사용하는 데 필요한 스토리지를 만들라는 메시지가 표시됩니다. 구독을 선택하여 스토리지 계정 및 Microsoft Azure Files 공유를 만듭니다.
Cloud Shell 도구 모음에서 환경 선택기를 사용하여 원하는 CLI 환경을 선택합니다. 이 문서에서는 Bash 환경을 사용합니다. PowerShell 환경을 사용해도 됩니다.
참고 항목
일부 명령의 경우 Bash 및 PowerShell 환경에서는 다른 구문이나 서식이 필요합니다. 자세한 내용은 Azure CLI를 성공적으로 사용하기 위한 팁을 참조하세요.
두 CLI 세션 준비
다음으로 두 Azure CLI 세션을 준비해야 합니다. Cloud Shell을 사용하는 경우 별도의 Cloud Shell 탭에서 이러한 세션을 실행합니다. 로컬 CLI 클라이언트를 사용하는 경우 개별 CLI 인스턴스를 실행합니다. 다음 작업에는 별도의 CLI 세션을 사용합니다.
- 첫 번째 세션은 IoT Hub와 통신하는 IoT 디바이스를 시뮬레이트합니다.
- 두 번째 세션은 시뮬레이션된 디바이스를 업데이트하고 IoT Hub를 쿼리합니다.
Cloud Shell을 사용하는 경우 다음 단계로 건너뜁니다. 그렇지 않으면 첫 번째 CLI 세션에서 az login 명령을 실행하여 Azure 계정에 로그인합니다.
Cloud Shell을 사용하는 경우 Azure 계정에 자동으로 로그인됩니다. Azure CLI 셸 세션과 IoT 허브 간의 모든 통신을 인증하고 암호화합니다. 따라서 이 문서에는 연결 문자열과 같은 실제 디바이스에서 사용하는 추가 인증이 필요하지 않습니다. Azure CLI를 사용한 로그인에 대한 자세한 내용은 Azure CLI를 사용하여 로그인을 참조하세요.
az login첫 번째 CLI 세션에서 az extension add 명령을 실행합니다. 이 명령은 Azure CLI용 Microsoft Azure IoT 확장을 CLI 셸에 추가합니다. 확장은 Azure CLI에 IoT Hub, IoT Edge 및 IoT DPS(Device Provisioning Service) 고유의 명령을 추가합니다. 확장을 설치한 후에는 Cloud Shell 세션에서 다시 설치할 필요가 없습니다.
az extension add --name azure-iot참고 항목
이 문서에서는
azure-iot라는 최신 버전의 Azure IoT 확장이 사용됩니다. 레거시 버전은azure-cli-iot-ext라고 합니다. 한 번에 하나의 버전만 설치해야 합니다.az extension list명령을 사용하여 현재 설치된 확장의 유효성을 검사할 수 있습니다.az extension remove --name azure-cli-iot-ext를 사용하여 레거시 버전의 확장을 제거합니다.az extension add --name azure-iot를 사용하여 새 버전의 확장을 추가합니다.설치한 확장을 확인하려면
az extension list를 사용합니다.두 번째 CLI 세션을 엽니다. 브라우저에서 Cloud Shell을 사용하는 경우 첫 번째 CLI 세션의 도구 모음에서 새 세션 열기 아이콘을 선택합니다. CLI를 로컬로 사용하는 경우 두 번째 CLI 인스턴스를 엽니다.
디바이스 만들기 및 시뮬레이션
이 섹션에서는 CLI 세션에서 IoT Hub에 대한 디바이스 ID를 만든 다음 해당 디바이스 ID를 사용하여 디바이스를 시뮬레이션합니다. 시뮬레이션된 디바이스는 두 번째 CLI 세션에서 예약하는 작업에 응답합니다.
시뮬레이트된 디바이스를 만들고 시작 하려면 다음을 실행합니다.
첫 번째 CLI 세션에서 az iot hub device-identity create 명령을 실행하여 다음 자리 표시자를 해당 값으로 바꿉니다. 이 명령은 시뮬레이션된 디바이스에 대한 디바이스 ID를 만듭니다.
{DeviceName}. 시뮬레이션된 디바이스의 이름입니다.
{HubName}. IoT Hub의 이름입니다.
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName}첫 번째 CLI 세션에서 az iot device simulate 명령을 실행하여 다음 자리 표시자를 해당 값으로 바꿉니다. 이 명령은 이전 단계에서 만든 디바이스를 시뮬레이션합니다. 또한 이 명령은 초기화될 때 디바이스의 해당 디바이스 쌍에서 해당 연결 채널을 reported 속성으로 보고하도록 시뮬레이션된 디바이스를 구성합니다.
{DeviceName}. 시뮬레이션된 디바이스의 이름입니다.
{HubName}. IoT Hub의 이름입니다.
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \ --init-reported-properties '{"connectivity":{"type": "cellular"}}'팁
기본적으로 az iot device simulate 명령은 메시지 간에 3초 간격으로 100개의 디바이스-클라우드 메시지를 보냅니다. 시뮬레이션은 모든 메시지가 전송된 후 종료됩니다. 시뮬레이션을 더 오래 실행하려면
--msg-count매개 변수를 사용하여 더 많은 메시지를 지정하거나--msg-interval매개 변수를 사용하여 메시지 간에 더 긴 간격을 지정할 수 있습니다. 명령을 다시 실행하여 시뮬레이션된 디바이스를 다시 시작할 수도 있습니다.
디바이스 쌍 업데이트
디바이스 ID가 만들어지면 디바이스 쌍이 IoT Hub에서 암시적으로 생성됩니다. 이 섹션에서는 두 번째 CLI 세션을 사용하여 이전 섹션에서 만든 디바이스 ID와 연결된 디바이스 쌍의 태그 집합을 업데이트합니다. 디바이스 쌍 태그를 사용하여 IoT 솔루션에서 디바이스를 구성하고 관리할 수 있습니다. 태그를 사용하여 디바이스를 관리하는 방법에 대한 자세한 내용은 Azure IoT Hub에서 디바이스 쌍 태그를 사용하여 디바이스를 관리하는 방법을 참조하세요.
첫 번째 CLI 세션에서 시뮬레이트된 디바이스가 실행 중인지 확인합니다. 그렇지 않은 경우 디바이스 만들기 및 시뮬레이션에서 az iot device simulate 명령을 다시 실행하여 다시 시작합니다.
두 번째 CLI 세션에서 az iot hub device-twin update 명령을 실행하여 다음 자리 표시자를 해당 값으로 바꿉니다. 이 예제에서는 이전 섹션에서 만든 디바이스 ID에 대해 디바이스 쌍에서 여러 태그를 업데이트합니다.
{DeviceName}. 디바이스의 이름입니다.
{HubName}. IoT Hub의 이름입니다.
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \ --tags '{"location":{"region":"US","plant":"Redmond43"}}'두 번째 CLI 세션에서 JSON 응답에 업데이트 작업의 결과가 표시되는지 확인합니다. 다음 JSON 응답 예제에서는
az iot hub device-twin updateCLI 명령의{DeviceName}자리 표시자에SampleDevice를 사용했습니다.{ "authenticationType": "sas", "capabilities": { "iotEdge": false }, "cloudToDeviceMessageCount": 0, "connectionState": "Connected", "deviceEtag": "MTA2NTU1MDM2Mw==", "deviceId": "SampleDevice", "deviceScope": null, "etag": "AAAAAAAAAAI=", "lastActivityTime": "0001-01-01T00:00:00+00:00", "modelId": "", "moduleId": null, "parentScopes": null, "properties": { "desired": { "$metadata": { "$lastUpdated": "2023-02-21T10:40:10.5062402Z" }, "$version": 1 }, "reported": { "$metadata": { "$lastUpdated": "2023-02-21T10:40:43.8539917Z", "connectivity": { "$lastUpdated": "2023-02-21T10:40:43.8539917Z", "type": { "$lastUpdated": "2023-02-21T10:40:43.8539917Z" } } }, "$version": 2, "connectivity": { "type": "cellular" } } }, "status": "enabled", "statusReason": null, "statusUpdateTime": "0001-01-01T00:00:00+00:00", "tags": { "location": { "plant": "Redmond43", "region": "US" } }, "version": 4, "x509Thumbprint": { "primaryThumbprint": null, "secondaryThumbprint": null } }
디바이스 쌍에 대한 IoT Hub 쿼리
IoT Hub는 devices라는 문서 컬렉션으로 IoT Hub에 대한 디바이스 쌍을 노출합니다. 이 섹션에서는 두 번째 CLI 세션을 사용하여 IoT Hub에 대한 디바이스 쌍 집합에서 두 개의 쿼리를 실행합니다. 첫 번째 쿼리는 Redmond43 공장에 있는 디바이스 쌍만 선택하고 두 번째 쿼리는 셀룰러 네트워크를 통해 연결된 디바이스만 선택하도록 쿼리를 구체화합니다. 두 쿼리 모두 결과 집합의 처음 100개 디바이스만 반환합니다. 디바이스 쌍 쿼리에 대한 자세한 내용은 IoT Hub 디바이스 및 모듈 쌍에 대한 쿼리를 참조하세요.
첫 번째 CLI 세션에서 시뮬레이트된 디바이스가 실행 중인지 확인합니다. 그렇지 않은 경우 디바이스 만들기 및 시뮬레이션에서 az iot device simulate 명령을 다시 실행하여 다시 시작합니다.
두 번째 CLI 세션에서 az iot hub query 명령을 실행하여 다음 자리 표시자를 해당 값으로 바꿉니다. 이 예제에서는 Redmond43 공장에 있는 디바이스의 디바이스 쌍만 반환하도록 쿼리를 필터링합니다.
{HubName}. IoT Hub의 이름입니다.
az iot hub query --hub-name {HubName} \ --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \ --top 100두 번째 CLI 세션에서 JSON 응답에 쿼리 결과가 표시되는지 확인합니다.
{ "authenticationType": "sas", "capabilities": { "iotEdge": false }, "cloudToDeviceMessageCount": 0, "connectionState": "Connected", "deviceEtag": "MTA2NTU1MDM2Mw==", "deviceId": "SampleDevice", "deviceScope": null, "etag": "AAAAAAAAAAI=", "lastActivityTime": "0001-01-01T00:00:00+00:00", "modelId": "", "moduleId": null, "parentScopes": null, "properties": { "desired": { "$metadata": { "$lastUpdated": "2023-02-21T10:40:10.5062402Z" }, "$version": 1 }, "reported": { "$metadata": { "$lastUpdated": "2023-02-21T10:40:43.8539917Z", "connectivity": { "$lastUpdated": "2023-02-21T10:40:43.8539917Z", "type": { "$lastUpdated": "2023-02-21T10:40:43.8539917Z" } } }, "$version": 2, "connectivity": { "type": "cellular" } } }, "status": "enabled", "statusReason": null, "statusUpdateTime": "0001-01-01T00:00:00+00:00", "tags": { "location": { "plant": "Redmond43", "region": "US" } }, "version": 4, "x509Thumbprint": { "primaryThumbprint": null, "secondaryThumbprint": null } }두 번째 CLI 세션에서 az iot hub query 명령을 실행하여 다음 자리 표시자를 해당 값으로 바꿉니다. 이 예제에서는 셀룰러 네트워크를 통해 연결된 Redmond43 공장에 있는 디바이스의 디바이스 쌍만 반환하도록 쿼리를 필터링합니다.
{HubName}. IoT Hub의 이름입니다.
az iot hub query --hub-name {HubName} \ --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \ AND properties.reported.connectivity.type = 'cellular'" \ --top 100두 번째 CLI 세션에서 JSON 응답에 쿼리 결과가 표시되는지 확인합니다. 이 쿼리의 결과는 이 섹션의 이전 쿼리 결과와 일치해야 합니다.
이 문서에서는 다음 작업을 수행합니다.
- Azure CLI 세션에서 태그로 디바이스 메타데이터 추가
- 디바이스 쌍에서 디바이스 연결 정보를 보고한 디바이스 시뮬레이션
- Azure CLI 세션에서 SQL과 유사한 IoT Hub 쿼리 언어를 사용하여 디바이스 쌍 정보 쿼리
다음 단계
방법을 알아보려면 다음을 참조하세요.
디바이스에서 원격 분석을 보냅니다. 빠른 시작: IoT 플러그 앤 플레이 디바이스에서 Azure IoT Hub로 원격 분석 보내기를 참조하세요.
디바이스 쌍의 desired 속성을 사용하여 디바이스를 구성합니다. 자습서: 백 엔드 서비스에서 디바이스 구성을 참조하세요.
사용자가 제어하는 앱에서 팬을 켜는 것과 같이 대화형으로 디바이스를 제어합니다. 빠른 시작: IoT Hub에 연결된 디바이스 제어를 참조하세요.