Device Update for IoT Hub로 업데이트 가져오기: 스키마 및 기타 정보

아티클
01/10/2024

Device Update for IoT Hub로 업데이트를 가져오려면 먼저 개념 및 방법 가이드를 검토해야 합니다. 가져오기 매니페스트 스키마 자체에 관한 자세한 내용은 아래를 참조하세요.

매니페스트 JSON 스키마 가져오기는 SchemaStore.org에 호스트됩니다.

스키마

속성	Type	설명	필수
$schema	`string`	JSON 스키마 참조.	아니요
updateId	`updateId`	고유 업데이트 식별자입니다.	예
description	`string`	선택적 업데이트 설명입니다. 최대 길이: 512자	아니요
호환성	`compatibility`	이 업데이트와 호환되는 디바이스 속성 집합의 목록입니다.	예
지침	`instructions`	설치 지침을 업데이트합니다.	예
files	`file` `[0-10]`	업데이트 페이로드 파일 목록입니다. 모든 파일 크기의 합계가 2GB를 초과하지 않을 수도 있습니다. 모든 명령 단계가 참조 단계인 경우 비어 있거나 null일 수도 있습니다.	아니요
manifestVersion	`string`	매니페스트 스키마 버전을 가져옵니다. 5.0이어야 합니다.	예
createdDateTime	`string`	날짜 및 시간 가져오기 매니페스트가 ISO 8601 형식으로 만들어졌습니다. 예: `"2020-10-02T22:18:04.9446744Z"`	예

추가 속성은 허용되지 않습니다.

UpdateId 개체

updateID 개체는 각 업데이트에 대한 고유 식별자입니다.

속성	Type	설명	필수
provider	`string`	업데이트를 만들거나 직접 담당하는 엔터티입니다. 회사 이름이 될 수 있습니다. 패턴: `^[a-zA-Z0-9.-]+$` 최대 길이: 64자	예
이름	`string`	업데이트 클래스의 식별자입니다. 디바이스 클래스 또는 모델 이름이 될 수 있습니다. 패턴: `^[a-zA-Z0-9.-]+$` 최대 길이: 64자	예
version	`string`	점으로 2~4부로 구분된 숫자 버전 번호입니다. 각 파트는 0에서 2147483647 사이의 숫자여야 하며 앞에 오는 0은 삭제됩니다. 패턴: `^\d+(?:\.\d+)+$` 예제: `"1.0"`, `"2021.11.8"`	예

추가 속성은 허용되지 않습니다.

예시:

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

호환성 개체

호환성 개체는 이 업데이트와 호환되는 디바이스의 속성을 설명합니다.

형식: object
최소 속성: 1
최대 속성: 5

각 속성은 문자열 유형의 이름 값 쌍입니다.

최소 속성 이름 길이: 1
최대 속성 이름 길이: 32
최소 속성 값 길이: 1
최대 속성 값 길이: 64

동일한 호환성 속성 세트를 둘 이상의 업데이트 공급자 및 이름 조합과 함께 사용할 수 없습니다.

예시:

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

instructions 개체

지침 개체는 업데이트 설치 지침을 제공합니다. 지침 개체에는 수행할 단계 목록이 포함되어 있습니다. 단계는 실행할 코드이거나 다른 업데이트에 대한 포인터일 수 있습니다.

속성	Type	설명	필수
steps	`array[1-10]`	배열의 각 요소는 inlineStep 개체 또는 referenceStep 개체여야 합니다.	예

추가 속성은 허용되지 않습니다.

예시:

{
  "instructions": {
    "steps": [
      {
        "type": "inline",
        ...
      },
      {
        "type": "reference",
        ...
      }
    ]
  }
}

inlineStep 개체

inline step 개체는 코드 실행을 수행하는 설치 명령 단계입니다.

속성	Type	설명	필수
type	`string`	코드 실행을 수행하는 명령 단계 유형입니다. `inline`이어야 합니다. 기본값은 값이 제공되지 않는 경우 `inline`으로 설정됩니다.	아니요
description	`string`	선택적 명령 단계 설명입니다. 최대 길이: 64자	아니요
handler	`string`	이 단계를 실행할 수 있는 디바이스의 처리기 ID입니다. 패턴: `^\S+/\S+:\d{1,5}$` 최소 길이: 5자 최대 길이: 32자 예: `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1`	예
files	`string` `[1-10]`	에이전트가 처리기에 전달할 파일 개체로 정의된 업데이트 파일의 이름입니다. 배열의 각 요소의 길이는 1과 255자 사이여야 합니다.	예
handlerProperties	`inlineStepHandlerProperties`	에이전트가 처리기에 인수로 전달할 JSON 개체입니다.	아니요

추가 속성은 허용되지 않습니다.

예시:

{
  "steps": [
    {
      "description": "pre-install script",
      "handler": "microsoft/script:1",
      "handlerProperties": {
        "arguments": "--pre-install"
      },
      "files": [
        "configure.sh"
      ]
    }
  ]
}

referenceStep 개체

reference step 개체는 다른 업데이트를 설치하는 설치 명령 단계입니다.

속성	Type	설명	필수
type	`referenceStepType`	다른 업데이트를 설치하는 명령 단계 유형입니다. `reference`이어야 합니다.	예
description	`stepDescription`	선택적 명령 단계 설명입니다. 최대 길이: 64자	아니요
updateId	`updateId`	고유 업데이트 식별자입니다.	예

추가 속성은 허용되지 않습니다.

예시:

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

파일 개체

file 개체는 업데이트 페이로드 파일(예: 이진, 펌웨어, 스크립트 등)입니다. 각 파일 개체는 업데이트 내에서 고유해야 합니다.

속성	Type	설명	필수
filename	`string`	페이로드 파일 이름을 업데이트합니다. 최대 길이: 255자	예
sizeInBytes	`number`	파일 크기(바이트 수)입니다. 최대 크기: 2147483648바이트	예
hashes	`fileHashes`	알고리즘 이름을 키로 사용하는, Base64로 인코딩된 파일 해시입니다. SHA-256 알고리즘 이상을 지정해야 하며 에이전트에서 지원하는 경우 추가 알고리즘을 지정할 수도 있습니다. 해시를 계산하는 방법에 대한 자세한 내용은 아래를 참조하세요.	예
relatedFiles	`relatedFile[0-4]`	하나 이상의 기본 페이로드 파일에 대한 관련 파일의 컬렉션입니다.	아니요
downloadHandler	`downloadHandler`	관련 파일을 처리하는 방법을 지정합니다.	relatedFiles를 사용하는 경우에만 예

추가 속성은 허용되지 않습니다.

예시:

{
  "files": [
    {
      "filename": "configure.sh",
      "sizeInBytes": 7558,
      "hashes": {...}
    }
  ]
}

fileHashes 개체

알고리즘 이름을 키로 사용하는, Base64로 인코딩된 파일 해시입니다. SHA-256 알고리즘 이상을 지정해야 하며 에이전트에서 지원하는 경우 다른 알고리즘을 지정할 수도 있습니다. 해시를 올바르게 계산하는 방법의 예는 AduUpdate.psm1 스크립트를 참조하세요.

속성	Type	설명	필수
sha256	`string`	SHA-256 알고리즘을 사용하여 Base64로 인코딩된 파일 해시 값입니다.	예

추가 속성이 허용됩니다.

예시:

{
  "hashes": {
    "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
  }
}

relatedFiles 개체

하나 이상의 기본 페이로드 파일에 대한 관련 파일의 컬렉션입니다.

속성	Type	설명	필수
filename	`string`	기본 페이로드 파일과 연결된 관련 파일 목록입니다.	예
sizeInBytes	`number`	파일 크기(바이트 수)입니다. 최대 크기: 2147483648바이트	예
hashes	`fileHashes`	알고리즘 이름을 키로 사용하는, Base64로 인코딩된 파일 해시입니다. SHA-256 알고리즘 이상을 지정해야 하며 에이전트에서 지원하는 경우 추가 알고리즘을 지정할 수도 있습니다. 해시를 계산하는 방법에 대한 자세한 내용은 아래를 참조하세요.	예
properties	`relatedFilesProperties` `[0-5]`	키-값 쌍은 5개로 제한됩니다. 여기서 키는 64개의 ASCII 문자로 제한되고 값은 JObject(최대 256개의 ASCII 문자 포함)입니다.	아니요

추가 속성이 허용됩니다.

예시:

"relatedFiles": [
  {
    "filename": "in1_in2_deltaupdate.dat",
    "sizeInBytes": 102910752,
    "hashes": {
      "sha256": "2MIldV8LkdKenjJasgTHuYi+apgtNQ9FeL2xsV3ikHY="
    },
    "properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "YmFYwnEUddq2nZsBAn5v7gCRKdHx+TUntMz5tLwU+24="
    }
  }
],

자세한 내용은 관련 파일 기능을 사용하여 여러 업데이트 파일 참조를 참조하세요.

downloadHandler 개체

관련 파일을 처리하는 방법을 지정합니다.

속성	Type	설명	필수
id	`string`	downloadHandler용 식별자입니다. ASCII 문자 64개로 제한합니다.	예

추가 속성은 허용되지 않습니다.

예시:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

다음 단계

가져오기 개념에 관해 자세히 알아봅니다.

준비되면 가져오기 프로세스를 단계별로 안내하는 가져오기 방법 가이드를 사용해 보세요.

다음을 통해 공유

Device Update for IoT Hub로 업데이트 가져오기: 스키마 및 기타 정보

스키마

UpdateId 개체

호환성 개체

instructions 개체

inlineStep 개체

referenceStep 개체

파일 개체

fileHashes 개체

relatedFiles 개체

downloadHandler 개체

다음 단계

피드백

피드백

추가 리소스