Updates - Import Update

Service:

Device Update

API Version:

2020-09-01

Import new update version.

POST https://{accountEndpoint}/deviceupdate/{instanceId}/v2/updates?action=import

URI Parameters

Name	In	Required	Type	Description
accountEndpoint	path	True	string	Account endpoint.
instanceId	path	True	string	Account instance identifier.
action	query	True	ImportAction	Import update action.

Request Body

Name	Required	Type	Description
files	True	FileImportMetadata[]	One or more update file properties like filename and source URL.
importManifest	True	ImportManifestMetadata	Import manifest metadata like source URL, file size/hashes, etc.

Responses

Name	Type	Description
202 Accepted		Accepted update import request; background operation location to track status is specified in Operation-Location response header. Headers Location: string Operation-Location: string
429 Too Many Requests		Too many requests; there is a rate limit on how many operations can be executed within a time period and there is also a limit on how many concurrent import and delete background operations can be executed.

Security

azure_auth_implicit

Azure Active Directory OAuth2 Implicit Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

azure_auth_code

Azure Active Directory OAuth2 AccessCode Flow

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token

Scopes

Name	Description
user_impersonation	impersonate your user account

azure_auth_application

Azure Active Directory OAuth2 Application Flow

Type: oauth2
Flow: application
Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token

Scopes

Name	Description
.default	client credential scope

azure_auth_password

Azure Active Directory OAuth2 Password Flow

Type: oauth2
Flow: password
Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Updates_ImportUpdate

Sample request

HTTP

POST https://contoso.api.adu.microsoft.com/deviceupdate/blue/v2/updates?action=import

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

Sample response

Status code:

202

Location: /deviceupdate/instanceId/v2/updates/operations/e4491c54-916f-443d-9094-bcca546ace2f
Operation-Location: /deviceupdate/instanceId/v2/updates/operations/e4491c54-916f-443d-9094-bcca546ace2f

Status code:

429

Definitions

Name	Description
FileImportMetadata	Metadata describing an update file.
ImportAction	Import update action.
ImportManifestMetadata	Metadata describing the import manifest, a document which describes the files and other metadata about an update version.
ImportUpdateInput	Import update input metadata.

FileImportMetadata

Metadata describing an update file.

Name	Type	Description
filename	string	Update file name as specified inside import manifest.
url	string	Azure Blob location from which the update file can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 4 hours.

ImportAction

Import update action.

Name	Type	Description
import	string	Import action.

ImportManifestMetadata

Metadata describing the import manifest, a document which describes the files and other metadata about an update version.

Name	Type	Description
hashes	object	A JSON object containing the hash(es) of the file. At least SHA256 hash is required. This object can be thought of as a set of key-value pairs where the key is the hash algorithm, and the value is the hash of the file calculated using that algorithm.
sizeInBytes	integer	File size in number of bytes.
url	string	Azure Blob location from which the import manifest can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 4 hours.

ImportUpdateInput

Import update input metadata.

Name	Type	Description
files	FileImportMetadata[]	One or more update file properties like filename and source URL.
importManifest	ImportManifestMetadata	Import manifest metadata like source URL, file size/hashes, etc.