Importando atualizações para a Atualização de Dispositivo para o 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 o Hub IoT, certifique-se de ter revisado os conceitos e o guia de instruções primeiro. Se você estiver interessado nos detalhes do esquema de manifesto de importação em si, veja abaixo.

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

Esquema

Propriedade	Type	Descrição	Obrigatório
$schema	`string`	Referência de esquema JSON.	Não
updateId	`updateId`	Identificador de atualização exclusivo.	Sim
descrição	`string`	Descrição da atualização opcional. Comprimento máximo: 512 caracteres	Não
compatibilidade	`compatibility`	Lista de conjuntos de propriedades do dispositivo com os quais esta atualização é compatível.	Sim
Instruções	`instructions`	Atualize as instruções de instalação.	Sim
ficheiros	`file` `[0-10]`	Lista de arquivos de carga útil de atualização. A soma de todos os tamanhos de ficheiro não pode exceder 2 GB. Pode estar vazio ou nulo se todas as etapas de instrução forem etapas de referência.	Não
manifestVersion	`string`	Importar versão do esquema de manifesto. Deve 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

Propriedades adicionais não são permitidas.

objeto updateId

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

Propriedade	Type	Descrição	Obrigatório
fornecedor	`string`	Entidade que está criando ou diretamente responsável pela atualização. Pode ser o nome de uma empresa. Padrão: `^[a-zA-Z0-9.-]+$` Comprimento máximo: 64 caracteres	Sim
Designação	`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
Versão	`string`	Números de versão numéricos separados por pontos de duas a quatro partes. Cada parte deve ter um número entre 0 e 2147483647 e zeros à esquerda serão descartados. Padrão: `^\d+(?:\.\d+)+$` Exemplos: `"1.0"`, `"2021.11.8"`	Sim

Propriedades adicionais não são permitidas.

Por exemplo:

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

objeto de compatibilidade

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

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

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

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

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

Por exemplo:

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

objeto de instruções

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 um código para executar ou um ponteiro para outra atualização.

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

Propriedades adicionais não são permitidas.

Por exemplo:

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

objeto inlineStep

Um objeto de etapa embutido é uma etapa de instrução de instalação que executa a execução de código.

Propriedade	Type	Descrição	Obrigatório
type	`string`	Tipo de etapa de instrução que executa a execução de código. Deve ser `inline`. O padrão é `inline` se nenhum valor for fornecido.	Não
descrição	`string`	Descrição opcional da etapa de instruções. 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: 5 caracteres Comprimento máximo: 32 caracteres Exemplos: `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1`	Sim
ficheiros	`string` `[1-10]`	Nomes de arquivos de atualização definidos como objetos de arquivo que o agente passará para o manipulador. Cada elemento na matriz deve ter comprimento entre 1 e 255 caracteres.	Sim
manipuladorPropriedades	`inlineStepHandlerProperties`	Objeto JSON que o agente passará para o manipulador como argumentos.	Não

Propriedades adicionais não são permitidas.

Por exemplo:

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

objeto referenceStep

Um objeto de etapa de referência é uma etapa de instrução de instalação que instala outra atualização.

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

Propriedades adicionais não são permitidas.

Por exemplo:

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

objeto de arquivo

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

Propriedade	Type	Descrição	Obrigatório
filename	`string`	Atualize o nome do arquivo de carga útil. Comprimento máximo: 255 caracteres	Sim
sizeInBytes	`number`	Tamanho do ficheiro em número de bytes. Tamanho máximo: 2147483648 bytes	Sim
hashes	`fileHashes`	Hashes de arquivo codificados em Base64 com nome de algoritmo como chave. Pelo menos o algoritmo SHA-256 deve ser especificado, e o algoritmo adicional pode ser especificado se suportado pelo agente. Veja 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 carga primária.	Não
baixarHandler	`downloadHandler`	Especifica como processar quaisquer arquivos relacionados.	Sim somente se estiver usando relatedFiles

Propriedades adicionais não são permitidas.

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 podem ser especificados se suportados pelo 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

Propriedades adicionais são permitidas.

Por exemplo:

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

objeto relatedFiles

Coleção de arquivos relacionados a um ou mais de seus arquivos de carga primária.

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

Propriedades adicionais 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="
    }
  }
],

Para obter mais informações, consulte Usar o recurso de arquivos relacionados para fazer referência a vários arquivos de atualização.

objeto downloadHandler

Especifica como processar quaisquer arquivos relacionados.

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óximos passos

Saiba mais sobre conceitos de importação.

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

Partilhar via

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

Esquema

objeto updateId

objeto de compatibilidade

objeto de instruções

objeto inlineStep

objeto referenceStep

objeto de arquivo

objeto fileHashes

objeto relatedFiles

objeto downloadHandler

Próximos passos

Comentários

Recursos adicionais