Device Update - Import Update

Servizio:: Device Update

Versione API:: 2026-06-01

Importare una nuova versione di aggiornamento. Si tratta di un'operazione a esecuzione prolungata; usare Operation-Location valore dell'intestazione della risposta per verificare lo stato dell'operazione.

POST https://{endpoint}/deviceUpdate/{instanceId}/updates:import?api-version=2026-06-01

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
endpoint	path	True	string (url)	Aggiornamento del dispositivo per l'endpoint dell'account dell'hub IoT (solo nome host, nessun protocollo).
instanceId	path	True	string	Identificatore dell'istanza dell'account dell'hub IoT aggiornamento del dispositivo.
api-version	query	True	string minLength: 1	Versione dell'API da usare per questa operazione.

Corpo della richiesta

Nome	Tipo	Descrizione
updateToImport	ImportUpdateInputItem[]	Aggiornamento da importare (vedere schema https://json.schemastore.org/azure-deviceupdate-import-manifest-5.0.json per informazioni dettagliate).

Risposte

Nome	Tipo	Descrizione
200 OK	Update	La richiesta ha avuto esito positivo.
202 Accepted		La richiesta è stata accettata per l'elaborazione, ma l'elaborazione non è ancora stata completata. Intestazioni Operation-Location: string
Other Status Codes	ErrorResponse	Risposta di errore imprevista.

Nome

Tipo

Descrizione

200 OK

Update

La richiesta ha avuto esito positivo.

202 Accepted

La richiesta è stata accettata per l'elaborazione, ma l'elaborazione non è ancora stata completata.

Intestazioni

Operation-Location: string

Other Status Codes

ErrorResponse

Risposta di errore imprevista.

Sicurezza

OAuth2Auth

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/authorize

Ambiti

Nome	Descrizione
https://api.adu.microsoft.com/.default

Esempio

DeviceUpdate_ImportUpdate

Esempio di richiesta

HTTP

POST https://contoso.api.adu.microsoft.com/deviceUpdate/blue/updates:import?api-version=2026-06-01

[
  {
    "importManifest": {
      "url": "http://test.blob.core.windows.net/test/uploadimportMan.json",
      "sizeInBytes": 816,
      "hashes": {
        "sha256": "O19LyyncPe1AGstOdkcmozLV8pSbBdqrE18HdYVohRc="
      }
    },
    "files": [
      {
        "filename": "file1.bin",
        "url": "http://test.blob.core.windows.net/test/upload1v5uww1q"
      },
      {
        "filename": "file2.bin",
        "url": "http://test.blob.core.windows.net/test/uploadkrmn5yw0"
      },
      {
        "filename": "file3.bin",
        "url": "http://test.blob.core.windows.net/test/uploaddq52ky5m"
      }
    ]
  }
]

Risposta di esempio

Codice di stato:: 202

Operation-Location: /deviceUpdate/blue/updates/operations/e4491c54-916f-443d-9094-bcca546ace2f?api-version=2026-06-01

Codice di stato:: 200

{
  "updateId": {
    "provider": "microsoft",
    "name": "adu",
    "version": "1.0.0.0"
  },
  "friendlyName": "Lab Sensor Update v1",
  "description": "Fix for critical vulnerability",
  "compatibility": [
    {
      "deviceManufacturer": "Microsoft",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "microsoft",
          "name": "sensor",
          "version": "1.0"
        }
      }
    ]
  },
  "manifestVersion": "5.0",
  "importedDateTime": "2020-04-22T14:01:43.8408797-07:00",
  "createdDateTime": "2019-09-11T17:00:00-07:00",
  "etag": "\"3fed3378-0c67-47d2-b796-296962c66cbb\""
}

Definizioni

Nome	Descrizione
Error	Dettagli errore.
ErrorResponse	Risposta di errore comune.
FileImportMetadata	Metadati che descrivono un file di aggiornamento.
ImportManifestMetadata	Metadati che descrivono il manifesto di importazione, un documento che descrive i file e altri metadati relativi a una versione di aggiornamento.
ImportUpdateInputItem	Importare i metadati degli elementi di input di aggiornamento.
InnerError	Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.
Instructions	Aggiorna il contenitore delle istruzioni di installazione.
Step	Aggiornare il passaggio dell'istruzione di installazione.
StepType	Tipo di passaggio.
Update	Aggiornare i metadati.
UpdateId	Aggiornare l'identificatore.

Error

Oggetto

Dettagli errore.

Nome	Tipo	Descrizione
code	string	Codice di errore definito dal server.
details	Error[]	Matrice di errori che hanno causato l'errore segnalato.
innererror	InnerError	Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.
message	string	Rappresentazione leggibile dell'errore.
occurredDateTime	string (date-time)	Data e ora in formato UTC in cui si è verificato l'errore.
target	string	Destinazione dell'errore.

ErrorResponse

Oggetto

Risposta di errore comune.

Nome	Tipo	Descrizione
error	Error	Dettagli dell'errore.

FileImportMetadata

Oggetto

Metadati che descrivono un file di aggiornamento.

Nome	Tipo	Descrizione
filename	string	Aggiornare il nome del file come specificato all'interno del manifesto di importazione.
url	string	Percorso BLOB di Azure da cui è possibile scaricare il file di aggiornamento tramite Aggiornamento dispositivi per l'hub IoT. Si tratta in genere di un URL BLOB protetto da firma di accesso condiviso di sola lettura con una scadenza impostata su almeno 4 ore.

ImportManifestMetadata

Oggetto

Metadati che descrivono il manifesto di importazione, un documento che descrive i file e altri metadati relativi a una versione di aggiornamento.

Nome	Tipo	Descrizione
hashes	object	Oggetto JSON contenente l'hash(es) del file. È necessario almeno l'hash SHA256. Questo oggetto può essere considerato come un set di coppie chiave-valore in cui la chiave è l'algoritmo hash e il valore è l'hash del file calcolato usando tale algoritmo.
sizeInBytes	integer (int64)	Dimensioni del file in numero di byte.
url	string	Percorso BLOB di Azure da cui è possibile scaricare il manifesto di importazione tramite Aggiornamento dispositivi per l'hub IoT. Si tratta in genere di un URL BLOB protetto da firma di accesso condiviso di sola lettura con una scadenza impostata su almeno 4 ore.

ImportUpdateInputItem

Oggetto

Importare i metadati degli elementi di input di aggiornamento.

Nome	Tipo	Descrizione
files	FileImportMetadata[]	Una o più proprietà del file di aggiornamento, ad esempio nome file e URL di origine.
friendlyName	string minLength: 1 maxLength: 512	Nome descrittivo dell'aggiornamento.
importManifest	ImportManifestMetadata	Importare metadati del manifesto, ad esempio URL di origine, dimensioni/hash del file e così via.

InnerError

Oggetto

Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.

Nome	Tipo	Descrizione
code	string	Codice di errore più specifico di quello fornito dall'errore contenitore.
errorDetail	string	Messaggio di errore interno o eccezione.
innerError	InnerError	Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.
message	string	Rappresentazione leggibile dell'errore.

Instructions

Oggetto

Aggiorna il contenitore delle istruzioni di installazione.

Nome	Tipo	Descrizione
steps	Step[]	Raccolta dei passaggi di installazione.

Step

Oggetto

Aggiornare il passaggio dell'istruzione di installazione.

Nome	Tipo	Valore predefinito	Descrizione
description	string minLength: 1 maxLength: 64		Descrizione passaggio.
files	string[]		Raccolta di nomi di file da passare al gestore durante l'esecuzione. Obbligatorio se il tipo di passaggio è inline.
handler	string minLength: 1 maxLength: 32		Identità del gestore che eseguirà questo passaggio. Obbligatorio se il tipo di passaggio è inline.
handlerProperties			Parametri da passare al gestore durante l'esecuzione.
type	StepType	inline	Tipo di passaggio.
updateId	UpdateId		Identità di aggiornamento figlio a cui si fa riferimento. Obbligatorio se il tipo di passaggio è riferimento.

StepType

Enumerazione

Tipo di passaggio.

Valore	Descrizione
inline	Tipo di step che esegue l'esecuzione del codice.
reference	Tipo di passaggio che installa un altro aggiornamento.

Update

Oggetto

Aggiornare i metadati.

Nome	Tipo	Valore predefinito	Descrizione
compatibility	object[]		Elenco delle informazioni sulla compatibilità degli aggiornamenti.
createdDateTime	string (date-time)		Data e ora in formato UTC in cui è stato creato l'aggiornamento.
description	string minLength: 1 maxLength: 512		Aggiornare la descrizione specificata dall'autore.
etag	string		Aggiornare ETag.
friendlyName	string minLength: 1 maxLength: 512		Nome descrittivo dell'aggiornamento specificato dall'utilità di importazione.
importedDateTime	string (date-time)		Data e ora in formato UTC in cui è stato importato l'aggiornamento.
installedCriteria	string		Stringa interpretata dal client di Aggiornamento dispositivi per determinare se l'aggiornamento è installato nel dispositivo. Deprecato nello schema del manifesto di importazione più recente.
instructions	Instructions		Aggiornare le istruzioni di installazione.
isDeployable	boolean	True	Indica se l'aggiornamento può essere distribuito in un dispositivo autonomamente.
manifestVersion	string		Versione dello schema del manifesto usata per importare l'aggiornamento.
referencedBy	UpdateId[]		Elenco delle identità di aggiornamento che fanno riferimento a questo aggiornamento.
scanResult	string		Aggiornare il risultato dell'analisi aggregata (calcolato dai risultati dell'analisi dei file di payload).
updateId	UpdateId		Aggiornare l'identità.
updateType	string		Tipo di aggiornamento. Deprecato nello schema del manifesto di importazione più recente.

UpdateId

Oggetto

Aggiornare l'identificatore.

Nome	Tipo	Descrizione
name	string	Aggiornare il nome.
provider	string	Provider di aggiornamento.
version	string	Aggiornare la versione.