User-defined functions client library reference
Important
A new version of the Azure Digital Twins service has been released. In light of the new service's expanded capabilities, the original Azure Digital Twins service (described in this documentation set) has been retired.
To view the documentation for the new service, visit the active Azure Digital Twins Documentation.
This document provides reference information for the Azure Digital Twins user-defined functions client library.
Helper methods
The client library defines helper methods for commonly used operations.
getSpaceMetadata(id) ⇒ space
Given a space identifier, this function retrieves the space from the graph.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| id | guid |
Space identifier |
getSensorMetadata(id) ⇒ sensor
Given a sensor identifier, this function retrieves the sensor from the graph.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| id | guid |
Sensor identifier |
getDeviceMetadata(id) ⇒ device
Given a device identifier, this function retrieves the device from the graph.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| id | guid |
Device identifier |
getSensorValue(sensorId, dataType) ⇒ value
Given a sensor identifier and its data type, this function retrieves the current value for that sensor.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| sensorId | guid |
Sensor identifier |
| dataType | string |
Sensor data type |
getSpaceValue(spaceId, valueName) ⇒ value
Given a space identifier and the value name, this function retrieves the current value for that space property.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
| valueName | string |
Space property name |
getSensorHistoryValues(sensorId, dataType) ⇒ value[]
Given a sensor identifier and its data type, this function retrieves the historical values for that sensor.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| sensorId | guid |
Sensor identifier |
| dataType | string |
Sensor data type |
getSpaceHistoryValues(spaceId, dataType) ⇒ value[]
Given a space identifier and the value name, this function retrieves the historical values for that property on the space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
| valueName | string |
Space property name |
getSpaceChildSpaces(spaceId) ⇒ space[]
Given a space identifier, this function retrieves the child spaces for that parent space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
getSpaceChildSensors(spaceId) ⇒ sensor[]
Given a space identifier, this function retrieves the child sensors for that parent space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
getSpaceChildDevices(spaceId) ⇒ device[]
Given a space identifier, this function retrieves the child devices for that parent space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
getDeviceChildSensors(deviceId) ⇒ sensor[]
Given a device identifier, this function retrieves the child sensors for that parent device.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| deviceId | guid |
Device identifier |
getSpaceParentSpace(childSpaceId) ⇒ space
Given a space identifier, this function retrieves its parent space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| childSpaceId | guid |
Space identifier |
getSensorParentSpace(childSensorId) ⇒ space
Given a sensor identifier, this function retrieves its parent space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| childSensorId | guid |
Sensor identifier |
getDeviceParentSpace(childDeviceId) ⇒ space
Given a device identifier, this function retrieves its parent space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| childDeviceId | guid |
Device identifier |
getSensorParentDevice(childSensorId) ⇒ space
Given a sensor identifier, this function retrieves its parent device.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| childSensorId | guid |
Sensor identifier |
getSpaceExtendedProperty(spaceId, propertyName) ⇒ extendedProperty
Given a space identifier, this function retrieves the property and its value from the space.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
| propertyName | string |
Space property name |
getSensorExtendedProperty(sensorId, propertyName) ⇒ extendedProperty
Given a sensor identifier, this function retrieves the property and its value from the sensor.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| sensorId | guid |
Sensor identifier |
| propertyName | string |
Sensor property name |
getDeviceExtendedProperty(deviceId, propertyName) ⇒ extendedProperty
Given a device identifier, this function retrieves the property and its value from the device.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| deviceId | guid |
Device identifier |
| propertyName | string |
Device property name |
setSensorValue(sensorId, dataType, value)
This function sets a value on the sensor object with the given data type.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| sensorId | guid |
Sensor identifier |
| dataType | string |
Sensor data type |
| value | string |
Value |
setSpaceValue(spaceId, dataType, value)
This function sets a value on the space object with the given data type.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| spaceId | guid |
Space identifier |
| dataType | string |
Data type |
| value | string |
Value |
log(message)
This function logs the following message within the user-defined function.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| message | string |
Message to be logged |
sendNotification(topologyObjectId, topologyObjectType, payload)
This function sends a custom notification out to be dispatched.
Kind: global function
| Parameter | Type | Description |
|---|---|---|
| topologyObjectId | guid |
Graph object identifier. Examples are space, sensor, and device ID. |
| topologyObjectType | string |
Examples are sensor and device. |
| payload | string |
The JSON payload to be sent with the notification. |
Return types
The response models returned from client reference helper methods are described below.
Space
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Space",
"friendlyName": "Conference Room",
"typeId": 0,
"parentSpaceId": "00000000-0000-0000-0000-000000000001",
"subtypeId": 0
}
Space methods
Parent() ⇒ space
This function returns the parent space of the current space.
ChildSensors() ⇒ sensor[]
This function returns the child sensors of the current space.
ChildDevices() ⇒ device[]
This function returns the child devices of the current space.
ExtendedProperty(propertyName) ⇒ extendedProperty
This function returns the extended property and its value for the current space.
| Parameter | Type | Description |
|---|---|---|
| propertyName | string |
Name of the extended property |
Value(valueName) ⇒ value
This function returns the value of the current space.
| Parameter | Type | Description |
|---|---|---|
| valueName | string |
Name of the value |
History(valueName) ⇒ value[]
This function returns the historical values of the current space.
| Parameter | Type | Description |
|---|---|---|
| valueName | string |
Name of the value |
Notify(payload)
This function sends a notification with the specified payload.
| Parameter | Type | Description |
|---|---|---|
| payload | string |
JSON payload to include in the notification |
Device
{
"id": "00000000-0000-0000-0000-000000000002",
"name": "Device",
"friendlyName": "Temperature Sensing Device",
"description": "This device contains a sensor that captures temperature readings.",
"type": "None",
"subtype": "None",
"typeId": 0,
"subtypeId": 0,
"hardwareId": "ABC123",
"gatewayId": "ABC",
"spaceId": "00000000-0000-0000-0000-000000000000"
}
Device methods
Parent() ⇒ space
This function returns the parent space of the current device.
ChildSensors() ⇒ sensor[]
This function returns the child sensors of the current device.
ExtendedProperty(propertyName) ⇒ extendedProperty
This function returns the extended property and its value for the current device.
| Parameter | Type | Description |
|---|---|---|
| propertyName | string |
Name of the extended property |
Notify(payload)
This function sends a notification with the specified payload.
| Parameter | Type | Description |
|---|---|---|
| payload | string |
JSON payload to include in the notification |
Sensor
{
"id": "00000000-0000-0000-0000-000000000003",
"port": "30",
"pollRate": 3600,
"dataType": "Temperature",
"dataSubtype": "None",
"type": "Classic",
"portType": "None",
"dataUnitType": "FahrenheitTemperature",
"spaceId": "00000000-0000-0000-0000-000000000000",
"deviceId": "00000000-0000-0000-0000-000000000001",
"portTypeId": 0,
"dataUnitTypeId": 0,
"dataTypeId": 0,
"dataSubtypeId": 0,
"typeId": 0
}
Sensor methods
Space() ⇒ space
This function returns the parent space of the current sensor.
Device() ⇒ device
This function returns the parent device of the current sensor.
ExtendedProperty(propertyName) ⇒ extendedProperty
This function returns the extended property and its value for the current sensor.
| Parameter | Type | Description |
|---|---|---|
| propertyName | string |
Name of the extended property |
Value() ⇒ value
This function returns the value of the current sensor.
History() ⇒ value[]
This function returns the historical values of the current sensor.
Notify(payload)
This function sends a notification with the specified payload.
| Parameter | Type | Description |
|---|---|---|
| payload | string |
JSON payload to include in the notification |
Value
{
"dataType": "Temperature",
"value": "70",
"createdTime": ""
}
Extended property
{
"name": "OccupancyStatus",
"value": "Occupied"
}
Next steps
Learn about Azure Digital Twins user-defined functions.