Share via

How to query Azure Digital Twins APIs for common tasks

  • Article

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 article shows query patterns to help you execute common scenarios for your Azure Digital Twins instance. This assumes that your Digital Twins instance is already running. You can use any REST client, such as Postman.

In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Name Replace with
YOUR_INSTANCE_NAME The name of your Azure Digital Twins instance
YOUR_LOCATION The region your instance is hosted on

Queries for spaces and types

This section shows sample queries to get more information about your provisioned spaces. Make authenticated GET HTTP requests with the sample queries, replacing the placeholders with values from your setup.

  • Get spaces which are root nodes.

    YOUR_MANAGEMENT_API_URL/spaces?$filter=ParentSpaceId eq null

  • Get a space by name and include devices, sensors, computed values, and sensor values.

    YOUR_MANAGEMENT_API_URL/spaces?name=Focus Room A1&includes=fullpath,devices,sensors,values,sensorsvalues

  • Get spaces and their device/sensor information, whose parent is the given space ID, and which are at levels two to five relative to the given space.

    YOUR_MANAGEMENT_API_URL/spaces?spaceId=YOUR_SPACE_ID&includes=fullpath,devices,sensors,values,sensorsvalues&traverse=Down&minLevel=1&minRelative=true&maxLevel=5&maxRelative=true

  • Get the space with the given ID, and include computed and sensor values.

    YOUR_MANAGEMENT_API_URL/spaces?ids=YOUR_SPACE_ID&includes=Values,sensors,SensorsValues

  • Get property keys for a particular space.

    YOUR_MANAGEMENT_API_URL/propertykeys?spaceId=YOUR_SPACE_ID

  • Get spaces with property key named AreaInSqMeters and its value is 30. You can also do string operations, for example, get spaces containing property key with name = X contains Y.

    YOUR_MANAGEMENT_API_URL/spaces?propertyKey=AreaInSqMeters&propertyValue=30

  • Get all names with name Temperature and associated dependencies and ontologies.

    YOUR_MANAGEMENT_API_URL/types?names=Temperature&includes=space,ontologies,description,fullpath

Queries for roles and role assignments

This section shows some queries to get more information on roles and their assignments.

  • Get all roles supported by Azure Digital Twins.

    YOUR_MANAGEMENT_API_URL/system/roles

  • Get all role assignments in your Digital Twins instance.

    YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=down

  • Get role assignments on a particular path.

    YOUR_MANAGEMENT_API_URL/roleassignments?path=/A_SPATIAL_PATH

Queries for devices

This section shows some examples of how you can use the Management APIs to get specific information about your devices. All API calls need to be authenticated GET HTTP requests.

  • Get all devices.

    YOUR_MANAGEMENT_API_URL/devices

  • Find all device statuses.

    YOUR_MANAGEMENT_API_URL/system/devices/statuses

  • Get a specific device.

    YOUR_MANAGEMENT_API_URL/devices/YOUR_DEVICE_ID

  • Get all devices attached to the root space.

    YOUR_MANAGEMENT_API_URL/devices?maxLevel=1

  • Get all devices attached to spaces at levels 2 through 4.

    YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4

  • Get all devices directly attached to a particular space ID.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID

  • Get all devices attached to a particular space and its descendants.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down

  • Get all devices attached to descendants of a space, excluding that space.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down&minLevel=1&minRelative=true

  • Get all devices attached to direct children of a space.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true

  • Get all devices attached to one of the ancestors of a space.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Up&maxLevel=-1&maxRelative=true

  • Get all devices attached to descendants of a space that are of level smaller than or equal to 5.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down&maxLevel=5

  • Get all devices attached to spaces that are at the same level as the space with ID YOUR_SPACE_ID.

    YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true

  • Get the IoT Hub device connection string for your device.

    YOUR_MANAGEMENT_API_URL/devices/YOUR_DEVICE_ID?includes=ConnectionString

  • Get device with the given hardware ID, including attached sensors.

    YOUR_MANAGEMENT_API_URL/devices?hardwareIds=YOUR_DEVICE_HARDWARE_ID&includes=sensors

  • Get sensors for particular data types, in this case Motion and Temperature.

    YOUR_MANAGEMENT_API_URL/sensors?dataTypes=Motion,Temperature

Queries for matchers and user-defined functions

  • Get all provisioned matchers and their IDs.

      YOUR_MANAGEMENT_API_URL/matchers

  • Get details about a particular matcher, including the spaces and user-defined function associated with it.

    YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_ID?includes=description, conditions, fullpath, userdefinedfunctions, space

  • Evaluate a matcher against a sensor and enable logging for debugging purposes. The return of this HTTP GET message tells you whether the matcher and the sensor belong to the data type.

      YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_ID/evaluate/YOUR_SENSOR_ID?enableLogging=true

  • Get the ID of the user-defined functions.

      YOUR_MANAGEMENT_API_URL/userdefinedfunctions

  • Get the contents of a particular user-defined function

      YOUR_MANAGEMENT_API_URL/userdefinedfunctions/YOUR_USER_DEFINED_FUNCTION_ID/contents

Queries for users

This section shows some sample API queries for managing users in Azure Digital Twins. Make an HTTP GET request replacing the placeholders with values from your setup.

  • Get all users.

    YOUR_MANAGEMENT_API_URL/users

  • Get a specific user.

    YOUR_MANAGEMENT_API_URL/users/ANY_USER_ID

Next steps

To learn how to authenticate with your Management API, read Authenticating with APIs.

To learn more about your API endpoints, read How to use Digital Twins Swagger.