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