Device Update - Import Update

服務:
Device Update
API 版本:
2026-06-01

匯入新的更新版本。 這是長時間執行的作業;使用 Operation-Location 回應標頭值來檢查作業狀態。

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

URI 參數

名稱 位於 必要 類型 Description
endpoint
 path True

string (url)

IoT 中樞帳戶端點的裝置更新（僅限主機名，沒有通訊協定）。
instanceId
 path True

string

IoT 中樞帳戶實例標識碼的裝置更新。
api-version
 query True

string

minLength: 1

用於此作業的 API 版本。

要求本文

名稱 類型 Description
updateToImport

ImportUpdateInputItem[]

要匯入的更新（如需詳細資訊，請參閱架構 https://json.schemastore.org/azure-deviceupdate-import-manifest-5.0.json）。

回應

名稱 類型 Description
200 OK

Update

要求已成功。
202 Accepted

要求已接受進行處理，但尚未完成處理。

標題

Operation-Location: string
Other Status Codes

ErrorResponse

未預期的錯誤回應。

安全性

OAuth2Auth

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱 Description
https://api.adu.microsoft.com/.default

範例

DeviceUpdate_ImportUpdate

範例要求

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"
      }
    ]
  }
]

範例回覆

狀態碼:
202 
Operation-Location: /deviceUpdate/blue/updates/operations/e4491c54-916f-443d-9094-bcca546ace2f?api-version=2026-06-01
狀態碼:
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\""
}

定義

名稱 Description
Error

錯誤詳細數據。
ErrorResponse

常見的錯誤回應。
FileImportMetadata

描述更新檔案的元數據。
ImportManifestMetadata

描述匯入指令清單的元數據，此檔描述有關更新版本的檔案和其他元數據。
ImportUpdateInputItem

匯入更新輸入項目元數據。
InnerError

物件，包含與目前對象有關錯誤更具體的資訊。
Instructions

更新安裝說明容器。
Step

更新安裝指示步驟。
StepType

步驟類型。
Update

更新元數據。
UpdateId

更新標識碼。

Error

Object

錯誤詳細數據。

名稱 類型 Description
code

string

伺服器定義的錯誤碼。
details

Error[]

導致回報錯誤的錯誤陣列。
innererror

InnerError

物件，包含與目前對象有關錯誤更具體的資訊。
message

string

錯誤的人類可讀取表示法。
occurredDateTime

string (date-time)

發生錯誤的 UTC 日期和時間。
target

string

錯誤的目標。

ErrorResponse

Object

常見的錯誤回應。

名稱 類型 Description
error

Error

錯誤詳情

FileImportMetadata

Object

描述更新檔案的元數據。

名稱 類型 Description
filename

string

更新匯入指令清單中指定的檔名。
url

string

Azure Blob 位置，IoT 中樞的裝置更新可從中下載更新檔案。 這通常是只讀 SAS 保護的 Blob URL，到期時間設定為至少 4 小時。

ImportManifestMetadata

Object

描述匯入指令清單的元數據，此檔描述有關更新版本的檔案和其他元數據。

名稱 類型 Description
hashes

object

包含檔案哈希的 JSON 物件。 至少需要SHA256哈希。 這個物件可以視為一組索引鍵/值組，其中索引鍵是哈希演算法，而值是使用該演算法計算的檔案哈希。
sizeInBytes

integer (int64)

檔案大小，以位元組數為單位。
url

string

Azure Blob 位置，IoT 中樞的裝置更新可從中下載匯入指令清單。 這通常是只讀 SAS 保護的 Blob URL，到期時間設定為至少 4 小時。

ImportUpdateInputItem

Object

匯入更新輸入項目元數據。

名稱 類型 Description
files

FileImportMetadata[]

一或多個更新檔案屬性，例如檔名和來源 URL。
friendlyName

string

minLength: 1
maxLength: 512

易記的更新名稱。
importManifest

ImportManifestMetadata

匯入指令清單元數據，例如來源 URL、檔案大小/哈希等等。

InnerError

Object

物件，包含與目前對象有關錯誤更具體的資訊。

名稱 類型 Description
code

string

比包含錯誤所提供的錯誤碼更具體。
errorDetail

string

內部錯誤或例外狀況訊息。
innerError

InnerError

物件，包含與目前對象有關錯誤更具體的資訊。
message

string

錯誤的人類可讀取表示法。

Instructions

Object

更新安裝說明容器。

名稱 類型 Description
steps

Step[]

安裝步驟的集合。

Step

Object

更新安裝指示步驟。

名稱 類型 預設值 Description
description

string

minLength: 1
maxLength: 64

步驟描述。
files

string[]

在執行期間要傳遞至處理程式的檔名集合。 如果步驟類型為內嵌，則為必要項。
handler

string

minLength: 1
maxLength: 32

將執行此步驟之處理程式的身分識別。 如果步驟類型為內嵌，則為必要項。
handlerProperties

執行期間要傳遞至處理程序的參數。
type

StepType

inline

步驟類型。
updateId

UpdateId

參考的子更新身分識別。 如果步驟類型為參考，則為必要。

StepType

列舉型別

步驟類型。

值 Description
inline

執行程式碼的步驟類型。
reference

安裝另一個更新的步驟類型。

Update

Object

更新元數據。

名稱 類型 預設值 Description
compatibility

object[]

更新相容性信息的清單。
createdDateTime

string (date-time)

建立更新的 UTC 日期和時間。
description

string

minLength: 1
maxLength: 512

更新建立者所指定的描述。
etag

string

更新ETag。
friendlyName

string

minLength: 1
maxLength: 512

匯入工具指定的易記更新名稱。
importedDateTime

string (date-time)

匯入更新的 UTC 日期和時間。
installedCriteria

string

由裝置更新用戶端解譯的字串，以判斷更新是否已安裝在裝置上。 在最新的匯入指令清單架構中已被取代。
instructions

Instructions

更新安裝指示。
isDeployable

boolean

True

更新是否可以自行部署到裝置。
manifestVersion

string

用來匯入更新的指令清單架構版本。
referencedBy

UpdateId[]

參考此更新的更新身分識別清單。
scanResult

string

更新匯總掃描結果（從承載檔案掃描結果計算）。
updateId

UpdateId

更新身分識別。
updateType

string

更新類型。 在最新的匯入指令清單架構中已被取代。

UpdateId

Object

更新標識碼。

名稱 類型 Description
name

string

更新名稱。
provider

string

更新提供者。
version

string

更新版本。