Devices - Create Or Update

Create a device entity.

PATCH {endpoint}/sensor-partners/{sensorPartnerId}/devices/{deviceId}?api-version=2023-11-01-preview

URI Parameters

Name In Required Type Description
deviceId
path True

string

Id of the device resource.

endpoint
path True

string

uri

The host name of the namespace, e.g. admaInstanceName.farmbeats.azure.net

sensorPartnerId
path True

string

Id of the sensor partner.

api-version
query True

string

The requested API version

Request Header

Media Types: "application/merge-patch+json"

Name Required Type Description
Authorization True

string

Please provide a valid bearer token for authorized API calls. Note that you might need to clear your browser cache if you tried un-authenticated calls before.

Request Body

Media Types: "application/merge-patch+json"

Name Type Description
description

string

Textual description of the resource.

deviceDataModelId

string

Id of the associated device data model.

hardwareId

string

Device hardwareId.

integrationId

string

Integration id for the device.

location

Location

Location model class.

name

string

Name to identify resource.

parentDeviceId

string

Parent device Id for this device.

properties

A collection of key value pairs that belongs to the resource. Each pair must not have a key greater than 50 characters and must not have a value greater than 150 characters. Note: A maximum of 25 key value pairs can be provided for a resource and only string, numeral and datetime (yyyy-MM-ddTHH:mm:ssZ) values are supported.

reportingIntervalInSeconds

integer

Interval at which the device sends data in seconds.

status

string

Status of the resource.

type

string

Type of device.

Responses

Name Type Description
200 OK

Device

Success

201 Created

Device

Created

Other Status Codes

ErrorResponse

Error

Headers

x-ms-error-code: string

Security

Authorization

Please provide a valid bearer token for authorized API calls. Note that you might need to clear your browser cache if you tried un-authenticated calls before.

Type: apiKey
In: header

Examples

Devices_CreateOrUpdate

Sample request

PATCH {endpoint}/sensor-partners/sp1/devices/d124?api-version=2023-11-01-preview

{
  "deviceDataModelId": "ddm124",
  "integrationId": "string",
  "type": "device",
  "hardwareId": "HD156",
  "reportingIntervalInSeconds": 10,
  "location": {
    "latitude": 23.5,
    "longitude": 42.7
  },
  "status": "new device",
  "name": "my device",
  "description": "description goes here",
  "properties": {
    "key1": "value1",
    "key2": 123.45
  }
}

Sample response

{
  "deviceDataModelId": "ddm124",
  "integrationId": "string",
  "type": "device",
  "hardwareId": "HD156",
  "reportingIntervalInSeconds": 10,
  "location": {
    "latitude": 23.5,
    "longitude": 42.7
  },
  "sensorPartnerId": "sp1",
  "id": "d123",
  "status": "new device",
  "createdDateTime": "2022-01-24T06:20:47Z",
  "modifiedDateTime": "2022-01-24T06:21:07Z",
  "eTag": "0401a5cc-0000-0700-0000-61ee45540000",
  "name": "my device",
  "description": "description goes here",
  "properties": {
    "key1": "value1",
    "key2": 123.45
  }
}
{
  "deviceDataModelId": "ddm124",
  "integrationId": "string",
  "type": "device",
  "hardwareId": "HD156",
  "reportingIntervalInSeconds": 10,
  "location": {
    "latitude": 23.5,
    "longitude": 42.7
  },
  "sensorPartnerId": "sp1",
  "id": "d123",
  "status": "new device",
  "createdDateTime": "2022-01-24T06:20:47Z",
  "modifiedDateTime": "2022-01-24T06:20:47Z",
  "eTag": "0401baca-0000-0700-0000-61ee453f0000",
  "name": "my device",
  "description": "description goes here",
  "properties": {
    "key1": "value1",
    "key2": 123.45
  }
}

Definitions

Name Description
Device

Device API model.

Error

An error from the Azure AgPlatform service.

ErrorResponse

An error response from the Azure AgPlatform service. See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses for ErrorResponse reference document.

InnerError

Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.

Location

Location model class.

Device

Device API model.

Name Type Description
createdBy

string

Created by user/tenant id.

createdDateTime

string

Date-time when resource was created, sample format: yyyy-MM-ddTHH:mm:ssZ.

description

string

Textual description of the resource.

deviceDataModelId

string

Id of the associated device data model.

eTag

string

The ETag value to implement optimistic concurrency.

hardwareId

string

Device hardwareId.

id

string

Id of the resource.

integrationId

string

Integration id for the device.

location

Location

Location model class.

modifiedBy

string

Modified by user/tenant id.

modifiedDateTime

string

Date-time when resource was last modified, sample format: yyyy-MM-ddTHH:mm:ssZ.

name

string

Name to identify resource.

parentDeviceId

string

Parent device Id for this device.

properties

A collection of key value pairs that belongs to the resource. Each pair must not have a key greater than 50 characters and must not have a value greater than 150 characters. Note: A maximum of 25 key value pairs can be provided for a resource and only string, numeral and datetime (yyyy-MM-ddTHH:mm:ssZ) values are supported.

reportingIntervalInSeconds

integer

Interval at which the device sends data in seconds.

sensorPartnerId

string

Id of the associated sensor partner.

status

string

Status of the resource.

type

string

Type of device.

Error

An error from the Azure AgPlatform service.

Name Type Description
code

string

Server-defined set of error codes.

details

Error[]

Array of details about specific errors that led to this reported error.

innererror

InnerError

Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.

message

string

Human-readable representation of the error.

target

string

Target of the error.

ErrorResponse

An error response from the Azure AgPlatform service. See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses for ErrorResponse reference document.

Name Type Description
error

Error

An error from the Azure AgPlatform service.

traceId

string

Unique trace Id.

InnerError

Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.

Name Type Description
code

string

Specific error code than was provided by the containing error.

innererror

InnerError

Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.

Location

Location model class.

Name Type Description
latitude

number

Latitude of the location.

longitude

number

Longitude of the location.