적용 대상:
IoT Edge 1.5
중요합니다
IoT Edge 1.5 LTS는 지원되는 릴리스입니다. IoT Edge 1.4 LTS는 2024년 11월 12일부터 수명이 종료됩니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.
IoT Edge 에이전트 및 IoT Edge 허브는 IoT Edge 런타임을 구성하는 두 가지 모듈입니다. 각 런타임 모듈의 책임에 대한 자세한 내용은 Azure IoT Edge 런타임 및 해당 아키텍처를 이해하세요.
이 문서에서는 런타임 모듈 트윈스의 desired 속성 및 reported 속성을 제공합니다. IoT Edge 디바이스에서 모듈을 배포하는 방법에 대한 자세한 내용은 모 듈을 배포하고 IoT Edge에서 경로를 설정하는 방법을 참조하세요.
모듈 쌍은 다음을 포함합니다.
desired 속성. 솔루션 백 엔드는 원하는 속성을 설정하고 모듈은 이를 읽습니다. 또한 모듈은 원하는 속성의 변경 내용에 대한 알림을 받습니다. 원하는 속성은 reported 속성과 함께 모듈 구성 또는 조건을 동기화하는 데 사용됩니다.
reported 속성. 모듈은 보고된 속성을 설정하고 솔루션의 백엔드는 이를 읽고 쿼리합니다. reported 속성은 desired 속성과 함께 모듈 구성 또는 조건을 동기화하는 데 사용됩니다.
Edge 에이전트 desired 속성
IoT Edge 에이전트에 대한 모듈 쌍은 $edgeAgent라고 불립니다. 디바이스에서 실행되는 IoT Edge 에이전트와 IoT Hub 간의 통신을 조정합니다. 단일 디바이스 또는 대규모 배포의 일부로 특정 디바이스에 배포 매니페스트를 적용할 때 desired 속성이 설정됩니다.
| 속성 | 설명 | 필수 |
|---|---|---|
| imagePullPolicy (이미지를 가져오는 정책) | 이미지를 끌어올 시기를 지정합니다. OnCreate 또는 Never. 이미지가 이미 디바이스에 있는 경우 Never 를 사용합니다. | 예 |
| 재시작 정책 | 모듈을 다시 시작해야 하는 경우 가능한 값은 Never: 실행되지 않으면 모듈을 다시 시작하지 않음, Always: 실행되지 않는 경우 항상 모듈 다시 시작, On-Unhealthy: 비정상인 경우 모듈 다시 시작입니다. 비정상은 상태 검사를 기반으로 Docker에서 보고하는 내용입니다(예: "비정상 - 컨테이너가 제대로 작동하지 않음", 실패 시: 실패하면 다시 시작). | 예 |
| 런타임 타입 | docker여야 합니다. | 예 |
| runtime.settings.minDockerVersion | 이 배포 매니페스트에 필요한 최소 Docker 버전을 지정합니다. | 예 |
| 런타임.설정.로그 옵션 | IoT Edge 에이전트 컨테이너에 대한 로깅 옵션을 사용하여 문자열화된 JSON을 지정합니다. Docker 로깅 옵션에 대해 자세히 알아봅니다. | 아니요 |
| runtime.settings.registryCredentials. {registryId}.username | 컨테이너 레지스트리의 사용자 이름을 지정합니다. Azure Container Registry의 경우 사용자 이름은 일반적으로 레지스트리 이름입니다. 레지스트리 자격 증명은 프라이빗 모듈 이미지에 필요합니다. | 아니요 |
| 런타임.설정.레지스트리자격증명.{registryId}.패스워드 | 컨테이너 레지스트리에 대한 암호입니다. | 아니요 |
| runtime.settings.registryCredentials. {registryId}.address | 컨테이너 레지스트리의 주소입니다. Azure Container Registry의 경우 주소는 일반적으로 {registryname}.azurecr.io입니다. | 아니요 |
| 스키마 버전 | 1.0 또는 1.1을 지정합니다. IoT Edge 버전 1.0.10에서 도입된 버전 1.1을 사용하는 것이 좋습니다. | 예 |
| 상태 | 모듈의 원하는 상태: 실행 중 또는 중지됨. | 필수 |
| systemModules.edgeAgent.type | docker여야 합니다. | 예 |
| 시스템모듈.edgeAgent.시작순서 | 모듈 위치의 정수(시작 순서)를 지정합니다. 0 이 첫 번째이고 최대 정수 (4294967295)가 마지막입니다. 값이 제공되지 않으면 기본값은 최대 정수입니다. | 아니요 |
| systemModules.edgeAgent.설정.이미지 | IoT Edge 에이전트 이미지의 URI를 지정합니다. IoT Edge 에이전트는 자체 업데이트할 수 없습니다. | 예 |
| 시스템모듈.edgesAgent.설정.생성옵션 | IoT Edge 에이전트 컨테이너를 만들기 위한 옵션을 사용하여 문자열화된 JSON을 지정합니다. Docker 만들기 옵션에 대해 자세히 알아봅니다. | 아니요 |
| systemModules.edgeAgent.configuration.id | 이 모듈을 배포한 배포의 ID입니다. | IoT Hub는 배포를 사용하여 매니페스트를 적용할 때 이 속성을 설정합니다. 배포 매니페스트의 일부가 아닙니다. |
| systemModules.edgeHub.type | docker여야 합니다. | 예 |
| systemModules.edgeHub.status | running이어야 합니다. | 예 |
| systemModules.edgeHub.restartPolicy | always여야 합니다. | 예 |
| systemModules.edgeHub.startupOrder | 모듈의 시작 순서에 해당하는 정수 값입니다. 0이 첫 번째이고 최대 정수(4294967295)가 마지막입니다. 값을 제공하지 않으면 기본값은 최대 정수입니다. | 아니요 |
| 시스템모듈.엣지허브.설정.이미지 | IoT Edge 허브 이미지의 URI입니다. | 예 |
| systemModules.edgeHub.settings.createOptions | IoT Edge 허브 컨테이너에 대한 만들기 옵션을 포함하는 문자열 형식 JSON입니다. Docker 만들기 옵션 | 아니요 |
| systemModules.edgeHub.configuration.id | 이 모듈을 배포한 배포의 ID입니다. | IoT Hub는 배포를 사용하여 매니페스트를 적용할 때 이 속성을 설정합니다. 배포 매니페스트의 일부가 아닙니다. |
| 모듈.{moduleId}.version | 이 모듈의 버전을 나타내는 사용자 정의 문자열입니다. | 예 |
| 모듈.{moduleId}.타입 | docker여야 합니다. | 예 |
| 모듈.{moduleId}.상태 | {실행 중 | 멈춤} | 예 |
| 모듈. {moduleId}.restartPolicy | {never | always} | 예 |
| 모듈。{moduleId}.startupOrder | 시작 순서에서 모듈의 위치에 대한 정수 값입니다. 0이 첫 번째이고 최대 정수(4294967295)가 마지막입니다. 값을 제공하지 않으면 기본값은 최대 정수입니다. | 아니요 |
| 모듈.{moduleId}.imagePullPolicy | {on-create | 절대} | 아니요 |
| 모듈. {moduleId}.env | 모듈에 전달할 환경 변수 목록입니다.
"<name>": {"value": "<value>"} 형식을 사용합니다. |
아니요 |
| 모듈.{moduleId}.설정.이미지 | 모듈 이미지에 대한 URI입니다. | 예 |
| 모듈.{moduleId}.settings.createOptions | 모듈 컨테이너에 대한 만들기 옵션을 포함하는 문자열 형식 JSON입니다. Docker 만들기 옵션 | 아니요 |
| 모듈. {moduleId}.configuration.id | 이 모듈을 배포한 배포의 ID입니다. | IoT Hub는 배포를 사용하여 매니페스트를 적용할 때 이 속성을 설정합니다. 배포 매니페스트의 일부가 아닙니다. |
| 버전 | 버전, 커밋 및 빌드가 있는 현재 반복입니다. | 아니요 |
Edge 에이전트 reported 속성
IoT Edge 에이전트의 보고된 특성에는 다음 세 가지 주요 정보가 포함하고 있습니다.
- 마지막으로 본 바람직한 속성의 애플리케이션 상태
- IoT Edge 에이전트에서 보고한 대로 디바이스에서 현재 실행 중인 모듈의 상태 및
- 디바이스에서 현재 실행 중인 원하는 속성의 복사본입니다.
현재 원하는 속성의 복사본은 디바이스가 최신 배포를 적용했는지 아니면 이전 배포 매니페스트를 계속 실행하고 있는지 확인하는 데 도움이 됩니다.
참고 항목
IoT Hub 쿼리 언어를 사용하여 IoT Edge 에이전트의 보고된 속성을 쿼리하여 대규모로 배포 상태를 조사할 수 있습니다. 단일 디바이스 또는 대규모 배포의 이해 섹션에서 상태에 대한 IoT Edge 에이전트 속성 사용 방법을 알아봅니다.
다음 표에는 원하는 속성에서 복사된 정보가 포함되어 있지 않습니다.
| 속성 | 설명 |
|---|---|
| 최종희망상태.코드 | IoT Edge 에이전트가 마지막으로 본 원하는 속성의 상태 코드입니다. 허용되는 값: 200 성공, 400 잘못된 구성, 412 잘못된 스키마 버전, 417 비어 있는 Desired 속성, 500 실패함. |
| lastDesiredStatus.description | 상태에 대한 텍스트 설명입니다. |
| 최종 원하는 버전 | 이 정수는 IoT Edge 에이전트에서 처리하는 desired 속성의 마지막 버전을 나타냅니다. |
| runtime.platform.OS | 디바이스에서 실행 중인 OS를 보고합니다. |
| 런타임 플랫폼 구조 | 디바이스의 CPU 아키텍처를 보고합니다. |
| 스키마 버전 | reported 속성의 스키마 버전입니다. |
| 시스템 모듈.에지 에이전트.실행 상태 | IoT Edge 에이전트의 보고된 상태: {running | unhealthy}. |
| 시스템모듈.엣지에이전트.상태설명 | IoT Edge 에이전트의 reported 상태에 대한 텍스트 설명입니다. |
| systemModules.edgeAgent.exitCode | 컨테이너가 종료되는 경우 IoT Edge 에이전트 컨테이너에서 보고하는 종료 코드입니다. |
| systemModules.edgeAgent.lastStartTimeUtc | IoT Edge 에이전트가 마지막으로 시작된 시간입니다. |
| systemModules.edgeAgent.lastExitTimeUtc | IoT Edge 에이전트가 마지막으로 종료된 시간입니다. |
| systemModules.edgeHub.runtimeStatus | IoT Edge 허브의 상태: { running | stopped | failed | backoff | unhealthy }. |
| 시스템 구성 요소.edgeHub.상태 설명 | 비정상인 경우 IoT Edge 허브의 상태에 대한 텍스트 설명입니다. |
| systemModules.edgeHub.exitCode | 컨테이너가 종료되는 경우 IoT Edge 허브 컨테이너에서 보고하는 종료 코드입니다. |
| systemModules.edgeHub.lastStartTimeUtc | IoT Edge 허브가 마지막으로 시작된 시간입니다. |
| systemModules.edgeHub.lastExitTimeUtc | IoT Edge 허브가 마지막으로 종료된 시간입니다. |
| systemModules.edgeHub.마지막재시작시간UTC | IoT Edge 허브가 마지막으로 다시 시작된 시간입니다. |
| 시스템 모듈.엣지 허브.재시작 횟수 | 이 모듈이 다시 시작 정책의 일부로 다시 시작된 횟수입니다. |
| 모듈. {moduleId}.runtimeStatus | 모듈의 상태: { running | stopped | failed | backoff | unhealthy }. |
| 모듈. {moduleId}.statusDescription | 비정상인 경우 모듈의 상태에 대한 텍스트 설명입니다. |
| 모듈.{moduleId}.exitCode | 컨테이너가 종료되는 경우 모듈 컨테이너가 보고하는 종료 코드입니다. |
| 모듈. {moduleId}.lastStartTimeUtc | 모듈이 마지막으로 시작된 시간입니다. |
| 모듈. {moduleId}.lastExitTimeUtc | 모듈이 마지막으로 종료된 시간입니다. |
| 모듈. {moduleId}.lastRestartTimeUtc | 모듈을 마지막으로 다시 시작된 시간입니다. |
| 모듈. {moduleId}.restartCount | 이 모듈이 다시 시작 정책의 일부로 다시 시작된 횟수입니다. |
| 버전 | 이미지의 버전입니다. 예: "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }. |
Edge 허브 desired 속성
IoT Edge 허브에 대한 모듈 쌍은 $edgeHub라고 하며, 디바이스에서 실행 중인 IoT Edge 허브와 IoT Hub 간의 통신을 조정합니다. 단일 디바이스 또는 대규모 배포의 일부로 특정 디바이스에 배포 매니페스트를 적용할 때 desired 속성이 설정됩니다.
| 속성 | 설명 | 배포 매니페스트에 필요합니다. |
|---|---|---|
| 스키마 버전 | 1.0 또는 1.1. IoT Edge 버전 1.0.10에서 도입된 버전 1.1을 사용하는 것이 좋습니다. | 예 |
| 경로. {routeName} | IoT Edge 허브 경로를 나타내는 문자열입니다. 자세한 내용은 경로 선언을 참조하세요. |
routes 요소는 존재하지만 비어 있을 수 있습니다. |
| storeAndForwardConfiguration.timeToLiveSecs | IoT Hub 또는 로컬 모듈과 관계없이 라우팅 엔드포인트에서 연결이 끊어진 경우 IoT Edge 허브에서 메시지를 보관하는 디바이스 시간(초)입니다. 이 시간은 전원이 꺼지거나 다시 시작되는 동안 유지됩니다. 자세한 내용은 오프라인 기능을 참조하세요. | 예 |
Edge 허브 reported 속성
| 속성 | 설명 |
|---|---|
| 최종 원하는 버전 | 이 정수는 IoT Edge 허브에서 처리하는 desired 속성의 마지막 버전을 나타냅니다. |
| 최종희망상태.코드 | IoT Edge 허브에서 마지막으로 표시된 desired 속성을 나타내는 상태 코드입니다. 허용되는 값: 200 성공, 400 잘못된 구성, 500 실패 |
| lastDesiredStatus.description | 상태에 대한 텍스트 설명입니다. |
| 클라이언트 | 상태 및 마지막 연결 시간으로 edgeHub에 연결된 모든 클라이언트입니다. 예: "clients": { "device2/SimulatedTemperatureSensor": { "status": "Connected", "lastConnectedTimeUtc": "2022-11-17T21:49:16.4781564Z" } }. |
| 클라이언트. {device 또는 moduleId}.status | 이 디바이스 또는 모듈의 연결 상태입니다. 가능한 값 {연결 | 끊김}. 모듈 ID만 연결이 끊긴 상태가 될 수 있습니다. 연결된 경우에만 IoT Edge 허브에 연결된 다운스트림 디바이스가 표시됩니다. |
| 클라이언트.{device 또는 moduleId}.lastConnectTime | 디바이스 또는 모듈이 마지막으로 연결된 시간입니다. |
| 클라이언트.{장치 또는 모듈 ID}.마지막 연결 해제 시간 | 디바이스 또는 모듈의 연결이 마지막으로 끊긴 시간입니다. |
| 스키마 버전 | reported 속성의 스키마 버전입니다. |
| 버전 | 이미지의 버전입니다. 예: "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }. |
다음 단계
이러한 속성을 사용하여 배포 매니페스트를 빌드하는 방법을 알아보려면 IoT Edge 모듈을 사용, 구성 및 다시 사용하는 방법에 대한 이해를 참조하세요.