Esquema de manifesto de importação da Atualização de Dispositivo do Azure para Hub IoT

Artigo
01/16/2025

Ao importar uma atualização para a Atualização de Dispositivo do Azure para Hub IoT, você também envia um arquivo de manifesto de importação JSON associado que define informações importantes sobre a atualização. Este artigo descreve o esquema usado para criar o arquivo de manifesto de importação JSON.

Para saber mais sobre conceitos de manifesto de importação e estrutura de arquivos, consulte Manifesto de importação da Atualização de Dispositivo do Azure para Hub IoT. Para saber como criar o arquivo, consulte Preparar uma atualização para importar para a Atualização de Dispositivo para Hub IoT.

Esquema

O esquema JSON do manifesto de importação é hospedado em SchemaStore.org e consiste nas propriedades a seguir. Nenhuma outra propriedade é permitida.

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.	Não
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.	Não
manifestVersion	`string`	Importar versão do esquema do manifesto. Deverá ser 5.0.	Sim
createdDateTime	`string`	Data e hora de criação do manifesto de importação no formato ISO 8601, por exemplo, `"2020-10-02T22:18:04.9446744Z"`.	Sim

Atualizar objeto

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. O provedor 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. O nome 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

Nenhuma outra propriedade é permitida.

Por exemplo:

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

Objeto Compatibility

O objeto compatibility descreve 1 a 5 propriedades de um dispositivo com o qual essa atualização é compatível. Cada propriedade é um par nome-valor de tipo string. O nome deve ter de 1 a 32 caracteres e o valor deve ter de 1 a 64 caracteres. Não é possível usar o mesmo conjunto exato de propriedades de compatibilidade com mais de uma combinação de nome e provedor de atualização.

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 steps a serem executadas. Nenhuma outra propriedade é permitida.

As etapas podem ser o código a ser executado ou ponteiros para outras atualizações. Um objeto de etapa usa inline como padrão se nenhum valor type for fornecido.

Propriedade	Type	Descrição	Obrigatório
etapas	`array[1-10]`	Cada elemento na matriz `steps` deve ser um objeto de etapa em linha ou um objeto de etapa de referência.	Sim

Por exemplo:

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

Objeto de etapa em linha

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.	Não
manipulador	`string`	Identidade do manipulador no dispositivo que pode executar esta etapa. Padrão: `^\S+/\S+:\d{1,5}$` Comprimento mínimo: cinco caracteres Comprimento máximo: 32 caracteres Exemplos: `microsoft/script:1`, `microsoft/swupdate:2`, `microsoft/apt:1`	Sim
arquivos	`string` `[1-10]`	Nomes dos arquivos de atualização definidos como objetos de arquivo que o agente passa para o manipulador. Cada comprimento de elemento deve ter de 1 a 255 caracteres.	Sim
handlerProperties	`inlineStepHandlerProperties`	Objetos JSON que o agente passa para o manipulador como argumentos.	Não

Nenhuma outra propriedade é permitida.

Por exemplo:

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

Objeto de etapa de referência

Um objeto de etapa reference é uma etapa de instrução de instalação para instalar 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.	Não
ID de atualização	`updateId`	Identificador de atualização exclusivo.	Sim

Nenhuma outra propriedade é permitida.

Por exemplo:

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

Objeto Files

Cada objeto files é um arquivo de conteúdo de atualização, como um binário, firmware, ou arquivo de script, que 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 algoritmos adicionais podem ser especificados se forem compatíveis com o agente. Consulte objeto Hashes para obter detalhes sobre como calcular o hash.	Sim
relatedFiles	`relatedFile[0-4]`	Coleção de arquivos relacionados a um ou mais arquivos de conteúdo primário. Para obter mais informações, consulte objeto relatedFiles.	Não
downloadHandler	`downloadHandler`	Especifica como processar qualquer arquivo relacionado.	Sim, se estiver usando `relatedFiles`. Para obter mais informações, consulte objeto downloadHandler.

Nenhuma outra propriedade é permitida.

Por exemplo:

{
  "files": [
    {  
      "fileName": "full-image-file-name",
      "sizeInBytes": 12345,
      "hashes": {...},
      "relatedFiles": [
        {
          "fileName": "delta-from-v1-file-name",
          "sizeInBytes": 1234,
          "hashes": {
            "SHA256": "delta-from-v1-file-hash"
          },
          "properties": {...}
        }  
      ],
      "downloadHandler": {
        "id": "microsoft/delta:1"
        }
    }
  ]
}

Objeto Hashes

O objeto hashes contém hashes de arquivo codificados em base64 com os nomes de 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

Outras propriedades são permitidas.

Por exemplo:

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

objeto relatedFiles

O objeto relatedFiles contém uma coleção de arquivos relacionados a um ou mais arquivos de conteúdo primário. Para obter mais informações, confira Usar o recurso de arquivos relacionados para referenciar vários arquivos de atualização.

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. Para obter mais informações, consulte Objeto Hashes.	Sim
properties	`relatedFilesProperties` `[0-5]`	Até cinco pares chave-valor, em que a chave é limitada a 64 caracteres ASCII e o valor é um objeto JObject com até 256 caracteres ASCII.	Não

Outras propriedades são permitidas.

Por exemplo:

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

Objeto downloadHandler

O objeto downloadHandler especifica como processar arquivos relacionados.

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

Nenhuma outra propriedade é permitida.

Por exemplo:

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

Compartilhar via

Esquema de manifesto de importação da Atualização de Dispositivo do Azure para Hub IoT

Esquema

Atualizar objeto

Objeto Compatibility

Objeto Instructions

Objeto de etapa em linha

Objeto de etapa de referência

Objeto Files

Objeto Hashes

objeto relatedFiles

Objeto downloadHandler

Comentários

Recursos adicionais

Compartilhar via

Esquema de manifesto de importação da Atualização de Dispositivo do Azure para Hub IoT

Esquema

Atualizar objeto

Objeto Compatibility

Objeto Instructions

Objeto de etapa em linha

Objeto de etapa de referência

Objeto Files

Objeto Hashes

objeto relatedFiles

Objeto downloadHandler

Conteúdo relacionado

Comentários

Recursos adicionais