Importando atualizações para a Atualização de Dispositivo para Hub IoT: esquema e outras informações

Artigo
01/10/2024

Se você quiser importar uma atualização para a Atualização de Dispositivo para Hub IoT, revise os conceitos e o guia de instruções primeiro. Confira abaixo se você estiver interessado nos detalhes do esquema de manifesto de importação em si.

O esquema JSON do manifesto de importação está hospedado em SchemaStore.org.

Esquema

Propriedade	Type	Descrição	Obrigatório
Esquema	`string`	Referência do esquema JSON.	No
ID de atualização	`updateId`	Identificador de atualização exclusivo.	Sim
descrição	`string`	Descrição de atualização opcional. Comprimento máximo: 512 caracteres	No
compatibilidade	`compatibility`	Lista de conjuntos das propriedades do dispositivo com as quais essa atualização é compatível.	Sim
instruções	`instructions`	Instruções de instalação de atualização.	Sim
arquivos	`file` `[0-10]`	Lista de arquivos de conteúdo de atualização. A soma de tamanhos de todos os arquivos não pode exceder 2 GB. Pode ser vazio ou nulo se todas as etapas de instrução forem etapas de referência.	No
manifestVersion	`string`	Importar versão do esquema do manifesto. Deverá ser 5.0.	Sim
createdDateTime	`string`	O manifesto de importação de data e hora foi criado no formato ISO 8601. Exemplo: `"2020-10-02T22:18:04.9446744Z"`	Sim

Não são permitidas propriedades adicionais.

Objeto updateId

O objeto updateID é um identificador exclusivo para cada atualização.

Propriedade	Type	Descrição	Obrigatório
provedor	`string`	Entidade que está criando ou é diretamente responsável pela atualização. Pode ser um nome de empresa. Padrão: `^[a-zA-Z0-9.-]+$` Comprimento máximo: 64 caracteres	Sim
name	`string`	Identificador de uma classe de atualização. Pode ser uma classe de dispositivo ou nome de modelo. Padrão: `^[a-zA-Z0-9.-]+$` Comprimento máximo: 64 caracteres	Sim
version	`string`	Dois a quatro blocos de números de versão numéricos separados por ponto. Cada bloco deve ser um número entre 0 e 2147483647 e os zeros à esquerda serão descartados. Padrão: `^\d+(?:\.\d+)+$` Exemplos: `"1.0"`, `"2021.11.8"`	Sim

Não são permitidas propriedades adicionais.

Por exemplo:

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

objeto compatibility

O objeto compatibility descreve as propriedades de um dispositivo com o qual essa atualização é compatível.

Tipo: object
Propriedades mínimas: 1
Propriedades máximas: 5

Cada propriedade é um par nome-valor da cadeia de caracteres de tipo.

Comprimento mínimo de nome de propriedade: 1
Comprimento máximo de nome de propriedade: 32
Comprimento mínimo do valor de propriedade: 1
Comprimento máximo do valor de propriedade: 64

O mesmo conjunto exato de propriedades de compatibilidade não pode ser usado com mais de uma combinação de provedor de atualização e nome.

Por exemplo:

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

Objeto instructions

O objeto instructions fornece as instruções de instalação da atualização. O objeto instructions contém uma lista de etapas a serem executadas. As etapas podem ser o código a ser executado ou um ponteiro para outra atualização.

Propriedade	Type	Descrição	Obrigatório
etapas	`array[1-10]`	Cada elemento na matriz deve ser um objeto inlineStep ou um objeto referenceStep.	Sim

Não são permitidas propriedades adicionais.

Por exemplo:

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

Objeto inlineStep

Um objeto de etapa inline é uma etapa de instrução de instalação que realiza a execução do código.

Propriedade	Type	Descrição	Obrigatório
tipo	`string`	Tipo de etapa de instrução que executa a execução de código. Deve ser `inline`. O padrão será `inline` se nenhum valor for fornecido.	No
descrição	`string`	Descrição da etapa de instrução opcional. Comprimento máximo: 64 caracteres	No
manipulador	`string`	Identidade do manipulador no dispositivo que pode executar esta etapa. Padrão: `^\S+/\S+:\d{1,5}$` Comprimento máximo: 5 caracteres Comprimento máximo: 32 caracteres Exemplos: `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1`	Sim
arquivos	`string` `[1-10]`	Nomes dos arquivos de atualização definidos como objetos de arquivo que o agente passará para o manipulador. Cada elemento na matriz deve ter um comprimento entre 1 e 255.	Sim
handlerProperties	`inlineStepHandlerProperties`	Objeto JSON que o agente passará para o manipulador como argumentos.	No

Não são permitidas propriedades adicionais.

Por exemplo:

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

Objeto referenceStep

Um objeto de etapa reference é uma etapa de instrução de instalação que instala outra atualização.

Propriedade	Type	Descrição	Obrigatório
tipo	`referenceStepType`	Tipo de etapa de instrução que instala outra atualização. Deve ser `reference`.	Sim
descrição	`stepDescription`	Descrição da etapa de instrução opcional. Comprimento máximo: 64 caracteres	No
ID de atualização	`updateId`	Identificador de atualização exclusivo.	Sim

Não são permitidas propriedades adicionais.

Por exemplo:

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

Objeto file

Um objeto file é um arquivo de conteúdo de atualização, por exemplo, binário, firmware, script etc. Cada objeto file deve ser exclusivo dentro de uma atualização.

Propriedade	Type	Descrição	Obrigatório
filename	`string`	Nome do arquivo de conteúdo de atualização. Comprimento máximo: 255 caracteres	Sim
sizeInBytes	`number`	Tamanho do arquivo em número de bytes. Tamanho máximo: 2147483648 bytes	Sim
hashes	`fileHashes`	Hashes de arquivo codificados em Base64 com o nome do algoritmo como chave. Pelo menos o algoritmo SHA-256 deve ser especificado e o algoritmo adicional pode ser especificado se for compatível com o agente. Confira abaixo detalhes sobre como calcular o hash.	Sim
relatedFiles	`relatedFile[0-4]`	Coleção de arquivos relacionados a um ou mais de seus arquivos de conteúdo primários.	Não
downloadHandler	`downloadHandler`	Especifica como processar qualquer arquivo relacionado.	Sim somente se estiver usando relatedFiles

Não são permitidas propriedades adicionais.

Por exemplo:

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

Objeto fileHashes

Hashes de arquivo codificados em Base64 com o nome do algoritmo como chave. Pelo menos o algoritmo SHA-256 deve ser especificado, e outros algoritmos poderão ser especificados se forem compatíveis com o agente. Para obter um exemplo de como calcular o hash corretamente, consulte a função Get-AduFileHashes no script AduUpdate.psm1.

Propriedade	Type	Descrição	Obrigatório
sha256	`string`	Valor de hash de arquivo codificado em Base64 usando o algoritmo SHA-256.	Sim

São permitidas propriedades adicionais.

Por exemplo:

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

objeto relatedFiles

Coleção de arquivos relacionados a um ou mais de seus arquivos de conteúdo primários.

Propriedade	Type	Descrição	Obrigatório
filename	`string`	Lista de arquivos relacionados associados a um arquivo de conteúdo primário.	Sim
sizeInBytes	`number`	Tamanho do arquivo em número de bytes. Tamanho máximo: 2147483648 bytes	Sim
hashes	`fileHashes`	Hashes de arquivo codificados em Base64 com o nome do algoritmo como chave. Pelo menos o algoritmo SHA-256 deve ser especificado e o algoritmo adicional pode ser especificado se for compatível com o agente. Confira abaixo detalhes sobre como calcular o hash.	Sim
properties	`relatedFilesProperties` `[0-5]`	Limite de cinco pares chave-valor, em que a chave é limitada a 64 caracteres ASCII e o valor é JObject (com até 256 caracteres ASCII).	Não

São permitidas propriedades adicionais.

Por exemplo:

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

Para obter mais informações, confira Usar o recurso de arquivos relacionados para referenciar vários arquivos de atualização.

Objeto downloadHandler

Especifica como processar qualquer arquivo relacionado.

Propriedade	Type	Descrição	Obrigatório
id	`string`	Identificador para downloadHandler. Limite de 64 caracteres ASCII.	Sim

Não são permitidas propriedades adicionais.

Por exemplo:

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

Próximas etapas

Saiba mais sobre os conceitos de importação.

Se você estiver pronto, experimente o Guia de instruções de importação, que o orientará passo a passo durante o processo de importação.

Importando atualizações para a Atualização de Dispositivo para Hub IoT: esquema e outras informações

Esquema

Objeto updateId

objeto compatibility

Objeto instructions

Objeto inlineStep

Objeto referenceStep

Objeto file

Objeto fileHashes

objeto relatedFiles

Objeto downloadHandler

Próximas etapas

Recursos adicionais