IoT Hub용 디바이스 업데이트로 업데이트 가져오기

2022-06-27

IoT Hub용 디바이스 업데이트에서 디바이스에 업데이트를 배포하려면 먼저 해당 업데이트를 디바이스 업데이트 서비스로 가져와야 합니다. 이 문서에서는 업데이트를 가져올 때 이해해야 할 몇 가지 중요한 개념에 대한 개요를 제공합니다.

매니페스트 가져오기

가져오기 매니페스트는 가져오는 업데이트에 대한 중요한 정보를 정의하는 JSON 파일입니다. 가져오기 프로세스의 일부로 가져오기 매니페스트와 연결된 업데이트 파일 또는 파일(예: 펌웨어 업데이트 패키지)을 모두 제출합니다. 가져오기 매니페스트에 정의된 메타데이터는 업데이트를 수집하는 데 사용됩니다. 일부 메타데이터는 배포 시에도 사용됩니다(예: 업데이트가 올바르게 설치되었는지 확인).

다음은 그 예입니다.

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "firmware.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "firmware.swu",
      "sizeInBytes": 7558,
      "hashes": {
        "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
      }
    }
  ],
  "createdDateTime": "2022-01-19T06:23:52.6996916Z",
  "manifestVersion": "4.0"
}

가져오기 매니페스트에는 IoT Hub에 대한 중요한 디바이스 업데이트를 나타내는 여러 항목이 포함되어 있습니다. 이러한 항목은 이 섹션에 설명되어 있습니다. 전체 가져오기 스키마에 대한 자세한 내용은 가져오기 매니페스트 JSON 스키마을 참조하세요.

신원 업데이트

업데이트 ID 또는 업데이트 ID는 IoT Hub용 디바이스 업데이트에서 업데이트를 식별하는 고유한 식별자입니다. 세 부분으로 구성됩니다.

공급자: 업데이트를 만들거나 직접 담당하는 엔터티입니다. 그것은 종종 회사 이름이 될 것입니다.
이름: 업데이트 클래스의 식별자입니다. 디바이스 클래스 또는 모델 이름이 되는 경우가 많습니다.
버전: 이 업데이트를 공급자와 이름이 같은 다른 업데이트와 구분하는 버전 번호입니다.

다음은 그 예입니다.

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

비고

UpdateId는 디바이스 업데이트 서비스에서만 사용되며 디바이스의 실제 소프트웨어 구성 요소 ID와 다를 수 있습니다.

호환성

호환성 업데이트를 설치할 수 있는 디바이스의 조건을 정의합니다. 디바이스에서 보고되는 임의의 키 값 쌍 집합인 디바이스 속성이 포함되어 있습니다. 일치하는 속성을 가진 디바이스만 배포에 적합합니다. 업데이트는 둘 이상의 디바이스 속성 집합을 사용하여 여러 디바이스 클래스와 호환될 수 있습니다.

다음은 Contoso와 Toaster를 디바이스 제조업체 및 모델로 보고하는 장치에만 배포할 수 있는 업데이트의 예입니다.

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

지시

지침 부분에는 디바이스 에이전트가 업데이트를 설치하는 데 필요한 단계 또는 정보가 포함되어 있습니다. 가장 간단한 업데이트에는 단일 인라인 단계가 포함됩니다. 해당 단계에서는 디바이스 에이전트에 등록된 처리기 사용하여 포함된 페이로드 파일을 실행합니다.

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

팁 (조언)

handler는 가져오기 매니페스트 버전 3.0 이하에서 updateType과 동일합니다.

업데이트에는 다음 두 단계 이상이 포함될 수 있습니다.

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

업데이트에는 디바이스 에이전트가 자체 가져오기 매니페스트를 사용하여 다른 업데이트를 설치하여 부모 및 자식 업데이트 관계를 설정하도록 지시하는 참조 단계가 포함될 수 있습니다. 예를 들어 토스터에 대한 업데이트에는 두 개의 자식 업데이트가 포함될 수 있습니다.

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

비고

업데이트에는 인라인 및 참조 단계의 조합이 포함될 수 있습니다.

파일

파일 파트에는 이름, 크기 및 해시와 같은 업데이트 페이로드 파일의 메타데이터가 포함되어 있습니다. IoT Hub용 디바이스 업데이트는 가져오기 프로세스 중에 무결성 유효성 검사를 위해 이 메타데이터를 사용합니다. 그런 다음 설치 전에 무결성 유효성 검사를 반복하기 위해 동일한 정보를 디바이스 에이전트에 전달합니다.

비고

참조 단계만 포함된 업데이트에는 부모 업데이트에 업데이트 페이로드 파일이 없습니다.

가져오기 매니페스트 만들기

모든 텍스트 편집기를 사용하여 매니페스트 JSON 파일을 가져올 수 있습니다. GitHub의 azure/iot-hub-device-update 프로그래밍 방식으로 가져오기 매니페스트를 만들기 위한 샘플 스크립트도 있습니다.

중요합니다

가져오기 매니페스트 JSON 파일 이름은 Azure 포털을 통해 가져올 때 .importmanifest.json로 끝나야 합니다.

팁 (조언)

Visual Studio Code 사용하여 가져오기 매니페스트를 만들 때 자동 완성 및 JSON 스키마 유효성 검사를 사용하도록 설정합니다.

업데이트 가져오기 제한

Device Update for IoT Hub 인스턴스마다 특정 제한이 적용됩니다. 아직 검토하지 않은 경우 디바이스 업데이트 제한을 참조하세요.

다음 단계

가져오기 프로세스에 대한 자세한 내용은 가져올 업데이트 준비를 참조하세요.
가져오기 매니페스트 스키마검토하십시오.