OSConfig 및 Azure IoT의 CommandRunner 기능과 상호 작용하는 방법

OSConfig에서 노출되는 대부분의 디바이스 속성은 구현 세부 정보에서 불연속적이고 추상화됩니다. 예를 들어 를 사용하여 HostName.desiredName 디바이스의 호스트 이름을 설정하는 경우 운영 체제 버전, 스크립팅 런타임 종속성 또는 타이밍 뉘앙스에 대해 걱정할 필요가 없습니다.

그러나 경우에 따라 유연성을 위해 단순성을 교환하려고 할 수 있습니다. 예:

디바이스의 관점에서 결과를 ping example.com 보고하려는 경우와 같이 디바이스에서 사용자 지정 정보를 검색해야 합니다.
기존 OSConfig desired/writable 속성이 없는 디바이스에서 구성해야 합니다.

OSConfig의 CommandRunner 기능을 사용하면 셸 명령/스크립트를 통해 사용자 지정 구성 및 보고를 수행할 수 있습니다. 또한 스크립팅이 필요하지 않은 특정 미리 정의된 작업(종료, 다시 부팅)도 포함됩니다.

팁

이 참조 문서에서는 CommandRunner 개념, 상호 작용 모델 등에 대해 설명합니다. 구체적인 사용 예제는 다음을 참조하세요.

상호 작용 모델 및 키 속성/필드

상호 작용 모델 요약

더 미묘한 사용이 가능하지만(이 문서의 뒷부분에서 설명) 핵심 상호 작용 모델은 간단합니다.

트윈에서 desired commandArguments 에 를 작성하여 명령 요청을 시작합니다.
트윈에서 보고된 commandStatus 내용을 읽어 결과를 가져옵니다.

commandArguments 및 commandStatus를 보여 주는 다이어그램

중요

이 다이어그램에 표시된 페이로드는 인/아웃 흐름을 강조하기 위해 제거됩니다. 여기에 표시되지 않는 필수 멤버를 포함한 전체 개체 모델은 전체 개체 모델을 참조하세요.

왕복 식별자는 다음과 같습니다. `commandId`

위의 다이어그램에서 및 commandStatus 는 모두 commandArguments 라는 commandId필드를 포함합니다. 이 비동기 작업 전체에서 요청 및 결과를 연결하는 왕복 식별자입니다.

호출자(관리자 또는 관리자 도구 체인)는 commandId 값을 선택합니다.

팁

commandId 은 에 commandArguments필요합니다. 호출자는 일반적으로 값을 선택할 때 다음 패턴 중 하나를 사용합니다.

"1"(첫 번째 요청의 경우), "2"(두 번째 요청의 경우) 등과 같은 단조 값입니다. 또는 "my_ping_command"와 같은 설명이 포함된 값

임시 탐색에 적합합니다. 계획이 필요하지 않으며 트윈 콘텐츠를 편집할 때 쉽게 입력할 수 있습니다.
UUID와 같은 높은 엔트로피 자동 생성 값

클라우드 솔루션 백 엔드가 프로그래밍 방식으로 값을 만들고 추적하는 대규모 프로그래밍 방식 사용에 적합합니다.

의 새 값 commandId 은 commandArguments 새 요청임을 알 수 있습니다. 단일 디바이스의 트윈 컨텍스트에서 새 commandId 를 채우는 것은 셸 환경에서 'Enter'를 누르는 것과 거의 유사합니다.

commandId 에서는 여러 요청을 추적할 수도 있습니다. 각 디바이스의 CommandRunner는 시간이 지남에 따라 여러 요청을 수신하고 상태 보고할 수 있습니다. 한편 commandArguments 각 디바이스 쌍의 및 commandStatus 구성 요소는 언제든지 하나의 요청만 설명할 수 있습니다. commandId 는 호출자가 이전 요청이 현재 에 설명 commandStatus된 것을 이해하고 제어할 수 있도록 하는 왕복 식별자입니다. 실제로 는 commandStatus "ID가 'foo'인 요청에 대해 상태 <...>"를 전달합니다.

언제 업데이트되 `commandStatus` 나요?

디바이스에 CommandRunner가 를 업데이트 commandStatus하는 두 가지 트리거가 있습니다.

백그라운드 새로 고침

commandStatus 는 정기적으로 업데이트됩니다(기본값은 30초). 기본적으로 이 백그라운드 새로 고침은 가장 최근 요청의 상태 나타냅니다.

실제로 commandArguments를 통해 요청을 제출한 후 약 30-60초 후에 commandStatus에서 해당 상태 확인할 수 있습니다.
refreshCommandStatus

refreshCommandStatus 는 다음과 같은 두 가지 고급 사용 사례를 해결하는 메커니즘입니다.
1. 을 통해 commandArguments시간이 지남에 따라 여러 요청을 실행했으며 가장 최근의 요청이 아닌 특정 요청에 대한 상태 확인하려고 합니다.
2. 최신 요청에만 관심이 있더라도 백그라운드 새로 고침을 기다리지 않으려는 경우
이 메커니즘을 트리거하려면 에 대한 commandArguments아래 개체 모델 설명서를 참조하세요.

CommandRunner를 사용하여 사용자 지정 구성 및 보고에 대한 모범 사례

크기 고려 사항

짧은 명령/스크립트 및 짧은 출력의 경우 트윈을 통해 직접 인라인으로 작업할 수 있습니다. 이 방법은 특히 IoT Hub 이외의 네트워크 또는 인증 종속성이 없는 장점이 있습니다. 이 방법의 주요 단점은 입력(스크립트/명령 텍스트 포함) 및 출력(캡처된 콘솔 출력 포함)이 각각 4KB로 제한된다는 것입니다.

더 긴 스크립트의 경우 스크립트를 다른 곳에 저장하고(예: GitHub) 트윈을 통해 OSConfig에 전달하는 최소 래퍼 명령에서 호출할 수 있습니다. 예제는 Azure IoT 및 OSConfig를 사용하여 사용자 지정 구성 및 보고를 참조하세요. 크기와 무관하게 트윈 콘텐츠가 단순히 해당 내용을 가리키는 GitHub 또는 이와 유사한 스크립트를 관리하는 것을 선호할 수도 있습니다.

콘솔 출력이 트윈에 비해 너무 큰 스크립트/명령의 경우 stdout이 아닌 온-프레미스 또는 클라우드 스토리지로 결과를 보내는 논리를 스크립트에 포함할 수 있습니다. 예제는 Azure IoT 및 OSConfig를 사용하여 사용자 지정 구성 및 보고를 참조하세요.
자체 포함된 비대화형 명령/스크립트 사용

왕복이 적으면 한 번의 왕복이 가장 좋습니다. OSConfig 및 CommandRunner는 대화형이 아닌 규모에 최적화되어 있습니다. CommandRunner를 직렬로 사용할 수 있지만(라이브 동기 터미널과 유사하게 한 명령씩) 환경이 최적이 아닙니다. 대화형 셸 프롬프트를 처리할 수 있는 방법이 없으며, 각 요청에 를 commandId 할당해야 하며, 쌍 동기화를 기다려야 합니다.

대신 CommandRunner를 대규모로 사용자 지정 구성 및 보고를 수행하는 방법으로 생각해 보세요. 비대화형 스크립트(또는 다시 부팅과 같은 미리 정의된 작업)를 하나의 디바이스 또는 수백만 개의 디바이스에 비동기적으로 배포할 수 있으며 시간이 지남에 따라 진화하는 경우에도 결과를 보고할 수 있습니다(예: 새 디바이스가 플릿에 조인함에 따라).

즉, 스페인의 모든 현재 및 향후 Ubuntu 20.04 디바이스에서 4개의 명령을 실행해야 한다고 가정합니다. 이를 CommandRunner의 4가지 개별 순차적 사용으로 생각하지 말고 페이로드에 네 개의 명령이 포함된 CommandRunner의 단일 사용으로 간주합니다. 한편 IoT Hub Configurations와 같은 클라우드 워크플로는 scope 있어야 하는 모든 현재 및 미래의 디바이스에 분산되도록 할 수 있습니다.

전체 개체 모델

중요

버전 1.0.3(2022년 6월 28일 게시됨)에는 기존 사용자에게 영향을 미칠 수 있는 멤버 이름에 대한 호환성이 손상되는 변경 내용이 포함되어 있습니다. 자세한 내용은 버전 1.0.3에서 멤버 이름이 PascalCase에서 camelCase로 전환됨을 참조하세요.

다음 정보는 DTDL 향상된 뷰뿐만 아니라 개체 모델의 일반 원하는/보고된 보기에도 적용됩니다. 자세한 내용은 "일반 desired/reported" 및 "DTDL 고급" 도구 체인에 대해 사용자가 알아야 할 OSConfig를 참조하세요.

commandArguments(관리자가 설정)

설명: 관리자의 입력은 새 명령 요청을 트리거하거나 commandStatus의 새로 고침을 트리거합니다.
경로: properties.desired.CommandRunner.commandArguments (CommandRunner 구성 요소 -->commandArguments 쓰기 가능한 속성)

멤버

이름	형식	참고
commandId	문자열	• 호출자가 지정한 요청 ID; 배경은 위 참조 • commandId가 비어 있으면 commandArguments가 무시됩니다. • commandId와 action 간의 상호 작용은 다음을 참조하세요.
action	enum/int	다음은 commandId의 새 값과 결합되어야 합니다. • 1(다시 부팅) • 2(종료) • 3(runCommand); 는 사용자 지정 구성 또는 보고를 위한 셸 명령/스크립트를 시작합니다. 다음은 이전에 사용한 CommandID와 결합되어야 합니다. • 4(refreshCommandStatus)로 인해 commandStatus가 commandId로 식별된 특정 요청을 설명합니다.
인수	문자열	• 작업이 1(다시 부팅) 또는 2(종료)인 경우 작업을 트리거하기 전에 지연할 선택적 시간(초)입니다. • 작업이 3(RunCommand)이면 실행할 명령줄(예: )입니다. `ping -c 2 example.com` • 다른 작업 유형에 대해 무시됨 • Azure IoT 쌍의 commandArguments 크기(일반적으로 인수 텍스트에 의해 지배됨)는 4KB로 제한됩니다. 더 긴 스크립트는 모범 사례를 참조하세요.
singleLineTextResult	boolean	• 작업이 3(RunCommand)인 경우 선택적 토글로 콘솔 출력에서 줄임표 제거 여부를 지정합니다. • 다른 작업 유형에 대해 무시됨
시간 제한	int	• 작업이 3(runCommand)이면 몇 초 후에 장기 실행 요청이 종료됩니다. • 선택 사항(기본값: 30) • 다른 작업 유형에 대해 무시됨

IoT Hub 및 실제 디바이스의 예

다시 부팅 요청:

"CommandRunner": {
   "__t": "c",
   "commandArguments": {
      "commandId": "my_reboot_cmd",
      "arguments": "",
      "timeout": 30,
      "singleLineTextResult": false,
      "action": 1
   }
}

사용자 지정 구성(표준 시간대) 요청:

"CommandRunner": {
   "__t": "c",
   "commandArguments": {
      "commandId": "my_timezone_cmd",
      "arguments": "timedatectl set-timezone Etc/UTC; timedatectl | grep Time",
      "timeout": 30,
      "singleLineTextResult": false,
      "action": 3
   }
}

추가 예제는 다음을 참조하세요.
- Azure IoT 및 OSConfig를 사용하여 디바이스 다시 부팅 또는 종료
- Azure IoT 및 OSConfig를 사용하여 사용자 지정 구성 및 보고

commandArguments(디바이스에서 승인)

설명: 관리자 쪽에서 commandArguments 값을 받은 디바이스의 OSConfig 에이전트에서 승인한 것입니다.
경로: properties.reported.CommandRunner.commandArguments (쓰기 가능한 속성의 commandArguments 디바이스 승인 부분)

멤버:

이름	형식	참고
값	map	를 미러`properties.desired.CommandRunner.commandArguments`, 디바이스가 온라인 상태이고 요청을 수신했음을 나타냅니다.
ac	int	상태 코드, 명목 대/소문자 값 `200`

commandStatus

설명: commandArguments를 통해 이전에 제출된 요청의 상태 및 출력을 제공합니다.
경로: properties.reported.CommandRunner.commandStatus (CommandRunner 구성 요소 -->commandStatus 읽기 전용 속성)

멤버

이름	형식	참고
commandId	문자열	• Commandstatus에서 현재 설명한 이전에 받은 요청을 식별합니다. • 기본적으로 가장 최근 요청이 표시됩니다. • 호출자는 위에서 설명한 refreshCommandStatus 메커니즘을 통해 특정 요청을 설명하기 위해 이 포커스를 변경할 수 있습니다.
resultCode	int	요청된 명령의 종료 코드입니다. `echo $?` bash의 와 유사
currentState	enum/int	• 명목 대/소문자 값 `2` (`succeeded`) • 가능한 값의 전체 목록은 메타데이터 를 참조하세요.
textResult	문자열	• 요청된 명령의 콘솔 출력 • 4KB로 제한된 Azure IoT 쌍의 commandStatus 크기(일반적으로 textResult 구성 요소에 의해 지배됨) 더 긴 출력은 모범 사례를 참조하세요.

IoT Hub 및 실제 디바이스의 예

다시 부팅 결과

"CommandRunner": {
    "__t": "c",
    "commandStatus": {
       "commandId": "my_reboot_cmd",
       "resultCode": 0,
       "textResult": "",
       "currentState": 2
    }
}

사용자 지정 구성(표준 시간대) 결과:

"CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "my_timezone_cmd",
      "testResult": "Time zone: UTC",
      "statusCode": 0
   }
}

추가 예제는 다음을 참조하세요.
- Azure IoT 및 OSConfig를 사용하여 디바이스 다시 부팅 또는 종료
- Azure IoT 및 OSConfig를 사용하여 사용자 지정 구성 및 보고

중요

다음 단계

OSConfig 시나리오 및 기능에 대한 개요는 다음을 참조하세요.

IoT용 OSconfig란?

구체적인 실제 예제는 다음을 참조하세요.

Last updated on 2023-06-21